A linguagem ubíqua além do código
A linguagem ubíqua ou linguagem onipresente é a linguagem falada no cotidiano de uma empresa. Ela utiliza as terminologias da realidade do negócio e ajuda na comunicação, contextualização, identificação e delimitação de conceitos.
Resumindo: linguagem ubíqua é quando todos falam a mesma língua e utilizam as mesmas palavras para definir as mesmas coisas.
Como você chama esse alimento?
Em Minas Gerais, São Paulo e no norte do Paraná, ele é conhecido como Mandioca, já no Rio de Janeiro e outras regiões do Nordeste ele é comumente chamado de Aipim, e ainda existem outras denominações: Castelinha, Uaipi e Macaxeira.
Este exemplo pode até não causar problema, pois são apenas maneiras diferentes de chamar o mesmo alimento, considerando as regionalidades e cultura de cada estado/município, mas imagine o seguinte cenário:
Você será contratado para desenvolver uma aplicação voltada à venda de veículos. Se você gosta de carros, provavelmente vai saber a diferença entre as seguintes palavras: carro, veículo e modelo. Com base nisso, qual definição daria para a seguinte informação: Chevrolet Onix ano 2022?
- Carro?
- Veículo?
- Modelo?
- Marca?
A expressão descrita acima pode ser definida da seguinte maneira:
É um veículo Onix, da Marca Chevrolet - ano 2022 e que possui diversas versões, sendo elas: LT Turbo MT, LTX Turbo MT, LT Turbo AT e LTZ Turbo AT.
Levando em consideração o cenário exposto, foi possível que com uma simples definição identificássemos um conjunto de palavras que devem ser usadas na linguagem Ubíqua.
As mais relevantes, neste caso, foram as seguintes: veículo, marca e versões - cada uma com um significado diferente dentro deste contexto.
Para deixar ainda mais claro, vamos analisar um cenário dentro da própria Vórtx: na área de Corporate Trust existe uma aplicação chamada VxInforma, que é utilizada pelas emissoras e securitizadoras para acompanhar as suas operações. Nesta aplicação, temos alguns perfis de acessos, sendo eles: Emissor, Operador e Administrador. Do ponto de vista da área de negócios, o cliente é um emissor, já do ponto de vista do desenvolvedor, o cliente pode ser qualquer aplicação que se conecta com a aplicação.
Estes são alguns exemplos que deixam claro a importância da utilização da linguagem ubíqua durante o planejamento e desenvolvimento das aplicações.
O time de desenvolvimento e/ou Product Manager devem conversar com os domain experts para entender as terminologias utilizadas pela área e documentar para que sejam utilizadas durante todo o ciclo de vida da aplicação.
O que é um especialista de domínio?
Em alguns casos, o especialista de domínio é a própria pessoa que vai utilizar o software, em outros não, o importante é que ela tenha autoridade em seu domínio para verificar a validade do modelo projetado.
Em alguns cenários, serão necessários vários especialistas de domínio para cobrir todo o contexto do software projetado. Uma pessoa não necessariamente deve saber tudo (por exemplo, para um ERP, seria necessário um especialista em domínio de cada área da empresa: vendas, compras, contabilidade, produção, estoque, etc).
Para conseguir um bom especialista de domínio é necessário encontrar uma pessoa (ou várias) que descreva o que o sistema deve fazer, explicando como o negócio funciona no campo considerado e que responda às perguntas mais complexas que podem ser feitas sobre o tema. É necessário alguém com autoridade para aprovar orientações e escolhas sobre como o software se encaixa nas necessidades do domínio e que facilite a extração de todos os conceitos do software e sua linguagem ubíqua.
A linguagem ubíqua além do código
Extrair a linguagem ubíqua, entender o negócio e conseguir escrever um código que descreva com clareza a regra de negócio explicitamente em seu domínio é DESAFIADOR. Compartilhar o conhecimento e passar adiante para novos integrantes do time é ASSUSTADOR.
Documentar pontos estratégicos e regras de negócio são táticas utilizadas há muito tempo em diversos paradigmas e plataformas de desenvolvimento. Cada vez mais é preciso gerar e documentar o código escrito com o objetivo de reduzir a curva de aprendizado para novos colaboradores. Porém, mais difícil do que escrever, é conseguir manter a documentação de forma clara, objetiva e atualizada.
As regras de negócios e os softwares evoluem constantemente e aí surge um questionamento: como conseguir manter uma boa documentação no decorrer do desenvolvimento do software?
Com o passar do tempo, no desenvolvimento de softwares, surgiram diversas formas de documentar. Um exemplo são as linguagens específicas como o JavaDoc, que fornece comentários e tags especiais para a geração de documentação automática, outra opção é utilizar ferramentas para escrever textos de forma manual, que fornecerá documentação completa, bonita e detalhada.
Segue um exemplo da utilização de tags e comentários no JavaDoc para gerar uma documentação automática:
public class Funcionarios {
private String matricula;
private Double salario;
/** Método para retorno da matrícula do funcionário
* @return String - Nr da Matrícula*/
public String getMatricula(){
return this.matricula;
}
}
Obviamente, é extremamente tentador executar um comando que vai varrer o código e gerar uma documentação completa "apenas" com comentários. Porém, ao ler o código, os comentários tornam a leitura "quebrada" e não fluida, deixando ele sujo e poluído. E um código deve ser limpo e legível.
Como gerar documentação automática e sem poluição no código
Dentro do ecossistema do Herbs (conjunto de bibliotecas open source, criadas e mantidas pela equipe de desenvolvedores da Vórtx) temos duas principais: o buchu e o herbsshelf.
Buchu é uma biblioteca que facilita a criação de casos de uso dentro do código, além de tornar o código muito mais legível e auto explicativo. Internamente, um caso de uso é responsável por controlar a interação entre entidades, repositórios e outros componentes do domínio.
Herbs Shelf é uma documentação autogerada com base em casos de uso e entidades de domínio. É uma maneira mais fácil de gerar documentações automáticas, sem poluição de código. Além de ser uma ótima maneira de comunicação e colaboração entre especialistas de domínio e desenvolvedores.
Vamos a um exemplo na prática de como criar um usecase utilizando o herbs. Você pode conhecer mais sobre o ecossistema herbs acessando a documentação, sugiro que comece pelo getting started.
const { usecase, step, Ok } = require('@herbsjs/herbs')
const { Contato } = require('../../entities')
const useCase = ({ contatoRepository }) => () =>
usecase('Busca todos contatos', {
request: {},
response: Contato,
authorize: () => Ok(),
'Busca os dados de todos os contatos cadastrados': step(async ctx => {
return (ctx.ret = await contatoRepository.findAll())
}),
})
module.exports = useCase
Exemplo 1: documentação gerada a partir do código escrito no step de buscar contatos.
.
Exemplo 2: Documentação completa com README.md na raiz do projeto com descrições gerais da aplicação desenvolvida e com mais usecases implementados.
.
Como podemos ver, o resultado é FANTÁSTICO, pois se trata de uma documentação que se apresenta com clareza, objetividade e além do mais, extremamente bonita.
Talvez, ao ver o exemplo, você tenha se questionado: descrição em português com código em inglês? Então vamos para o próximo tópico.
Quando devo programar com minha língua nativa?
Programar em português ou Inglês? Este, sem dúvidas, é um tema recorrente na nossa área, vou deixar minha opinião sobre o assunto e um exemplo de como utilizamos na Vórtx.
Os motivos para fazer a programação em inglês são muitos, alguns com argumentos bem fortes. Destaco dois que julgo de suma importância:
- Projetos Open Source - Caso esteja trabalhando em uma biblioteca e principalmente que tenha o objetivo de ser global, é fundamental que se esteja em inglês.
- Uniformidade de código - Fica mais fluido ler algo totalmente em inglês, seguindo o padrão da própria linguagem de programação.
O problema começa quando tentamos traduzir para outra língua termos que não são traduzíveis, pois não se trata apenas de traduzir o termo, ele precisa continuar fazendo sentido. Um exemplo é a palavra lastro utilizada na área de corporate para garantir que um determinado ativo tem valor. Traduções forçadas e confusas acabam dificultando a compreensão do código, podendo gerar erros na aplicação e na regra de negócio.
UMA SOLUÇÃO QUE ADOTAMOS NA VÓRTX
Mesmo não sendo uma solução perfeita, ela atende muito bem às nossas necessidades e se encaixa perfeitamente. Uma das soluções que utilizamos na vórtx é usar o português em toda a camada de negócio (domínio) e no restante utilizamos o inglês.
Essa estratégia de misturar o idioma pode parecer feia, porém, não é questão de ser "bonito" ou "feio", o código deve dizer exatamente o que faz e o motivo pelo qual existe.
Conclusão
A linguagem ubíqua deve ser utilizada do início ao fim no ciclo de desenvolvimento. Ela é fundamental para o conhecimento do negócio e facilita a compreensão de todos os envolvidos no projeto, reduzindo a concentração de conhecimento em apenas uma pessoa.
O código deve utilizar abstrações focadas, expressando nele todo o processo e as regras de negócio. Forçar traduções e conversões de termos podem trazer mais prejuízos que ganhos e apenas devem ser aplicados quando o domínio permite.
Referências
Evans, Eric. Domain-Driven Design: Atacando as complexidades no coração do software. terceira ed., Alta Books, 2016.
Linguagem Ubíqua + Código Expressivo = Felicidade :).
Disponível em: https://gabrielschade.github.io/2017/10/31/codigo-expressivo-talk.html. Último acesso em: 19 nov 2021
Domain-Driven Design. Disponível em: https://ajuda.gitlab.io/guia-rapido/design-patterns/domain-driven-design/. Último acesso em: 15 nov 2021
JavaDoc – Implementando documentação através do NetBeans. Disponível em:https://www.devmedia.com.br/javadoc-implementando-documentacao-atraves-do-netbeans/2495. Último acesso em: 19 nov 2021
Quando programar em sua língua nativa. Disponível em: https://robsoncastilho.com.br/2018/08/07/quando-programar-em-sua-lingua-nativa/. Último acesso em: 19 nov 2021