A linguagem ubíqua além do código

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?

exemplo de alimento - mandioca

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?

  1. Carro?
  2. Veículo?
  3. Modelo?
  4. 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.
imagem exemplo 2.

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.
imagem exemplo 3.

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:

  1. 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.
  2. 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