Maximizando a Compreensão do Código através da Documentação

A documentação do código é um aspecto crucial do desenvolvimento de software. Estes documentos devem apresentar descrições e explicações informativas sobre o código, tornando mais fácil para outros desenvolvedores entenderem, manterem e usarem a base de código. Uma boa documentação é benéfica não apenas para a equipe de desenvolvimento atual, mas também para futuros desenvolvedores, especialmente quando o código precisa ser atualizado ou alterado.

Uma das principais características de um bom código é a capacidade de manutenção do mesmo, que pode ser alcançada por meio de documentações compreensíveis e legíveis. Existem várias maneiras de documentar código, como por exemplo:

• Escolher nomes autoexplicativos para variáveis ​​e funções.
• Escrever breves comentários dentro do código para ajudar a contextualizar futuros desenvolvedores. Especialmente em trechos de código que apresentem uma maior complexidade.
• Criar documentações com imagens, com o intuito de tornar os conceitos apresentados menos abstratos, como por exemplo: diagramas de sequência e relacionamento de entidade; diagramas que sintetizam a arquitetura utilizada.
• No contexto do desenvolvimento de aplicações Back-end, escrever documentos de API (Interface de Programação de Aplicativos), descrevendo cada classe, método, argumento e valor de retorno.
• No contexto do desenvolvimento de aplicações Front-end, escrever documentações sobre o que é cada componente e sua utilidade.
• Elaborar uma estrutura de pastas que facilite a compreensão do propósito do código contido no arquivo correspondente.

Abaixo serão apresentados alguns tipos de documentações que podem agregar na gestão da qualidade dos projetos e garantir que o time que estiver trabalhando nesse projeto no futuro consiga expandir, atualizar e refatorar o código com mais facilidade.

DOCSTRING

Uma “Docstring” em programação é uma string literal especificada no código-fonte que é usada, como um comentário, para documentar um segmento específico de código. Esta documentação explica claramente o que a função faz, seus parâmetros de entrada e seu valor de retorno.

def multiply_numbers(x, y):     “””     This function multiplies two numbers.     Parameters:     x (int): First number of multiplication.     y (int): Second number of multiplication.     Returns:     int: The multiplication of x and y.     “””     return a * b

Essa documentação fornece explicações claras e detalhadas de como o código funciona. Sendo assim, é essencial para que outros desenvolvedores tenham mais facilidade no processo de compreender o código e modificá-lo, caso necessário.

No contexto do Backend, a depender do Framework que se está utilizando, é possível aproveitar a “Docstring” como documentação para o Swagger. O Swagger, também conhecido como OpenAPI, é uma especificação independente de linguagem que tem como finalidade descrever e documentar APIs REST.

O Swagger oferece uma plataforma única e conveniente para a documentação, teste e descrição das estruturas de uma API. Documentar APIs é crucial para fornecer informações aos usuários sobre os endpoints disponíveis para utilização. O Swagger simplifica significativamente o processo de documentação, pois ele automaticamente identifica métodos com atributos GET, PUT, POST e DELETE, e gera a documentação correspondente. Além disso, o Swagger mantém essa documentação atualizada de forma automática, facilitando a adaptação às mudanças implementadas na API.

Figura 1- Interface gráfica do Swagger. (Imagem copiada da página)

README

Um arquivo README é um componente essencial de qualquer projeto, pois fornece informações e documentação cruciais para usuários e desenvolvedores. Este documento deve apresentar as seguintes informações:

• Introdução: O README deve começar com uma breve introdução que explica do que se trata o projeto e sua finalidade. Esta seção deve fornecer uma visão geral de alto nível do projeto e suas principais características.

• Instalação: O README deve apresentar instruções claras sobre como instalar e configurar o projeto. Esta seção deve descrever quaisquer dependências ou pré-requisitos necessários para que o projeto seja executado com êxito. Deve incluir comandos, scripts ou links para guias de instalação mais detalhados.

• Documentação: Caso o projeto tenha documentação adicional como Contrato de API, documentação da arquitetura do projeto, documentação das ferramentas utilizadas no desenvolvimento, guias de usuários ou tutoriais, é recomendável incluir links ou referências a eles no arquivo README.

CONTRATO DE API

O contrato de API é um acordo formal entre o provedor e o consumidor de uma API que descreve as expectativas e responsabilidades de cada parte e especifica as regras e requisitos para usar a API. É um documento que descreve como a API funciona e como ela deve ser usada.

Recomenda-se o desenvolvimento do contrato API antes da implementação do código da API em si. Desta forma é possível validar com os desenvolvedores Front-end se o que está planejado no contrato se enquadra no que é esperado e se está estruturado da melhor forma para ser consumida pelo Front-end. Este documento deve apresentar as seguintes informações: 

• Método HTTP dos endpoints
• Descrição do objetivo dos endpoints
• Formato e estrutura dos parâmetros aceitos ou requeridos pelos endpoints
  • Parâmetros da rota da URL
  • Parâmetros de Consulta
  • Parâmetros de Cookie
  • Parâmetros de Cabeçalho
• Formato e estrutura da requisição aceita pelos endpoints
• Formato e estrutura da resposta que se espera dos endpoints
• Observações sobre o funcionamento e características específicas dos endpoints

Figura 2 – Exemplo de Contrato de API.

DOCUMENTAÇÃO DA ARQUITETURA

A documentação da arquitetura de software fornece uma visão de alto nível do design do sistema, facilitando a compreensão da estrutura, do propósito e dos relacionamentos entre os componentes. Esta documentação é um elemento central na criação de um entendimento comum entre todos os membros da equipe de desenvolvimento, aprimorando a comunicação e promovendo uma compreensão mais profunda do design e funcionalidade do sistema.

Ela desempenha um papel crítico em diferentes fases do ciclo de vida do software, auxiliando não apenas no desenvolvimento inicial, mas também na manutenção, refatoração e expansão contínua do sistema. Além disso, a documentação de arquitetura de software se torna uma valiosa ferramenta para os novos membros da equipe, permitindo-lhes entender o sistema de forma rápida e eficaz.

Esta documentação deve incluir alguns elementos-chave, tais como:

• Visão geral do sistema e seu propósito: visão geral do sistema, destacando seu propósito e contexto dentro da organização. Isso ajuda a estabelecer o cenário para compreender por que o sistema foi projetado da maneira como é.

• Visão de alto nível e interações: visão do sistema destacando como ele interage com outros sistemas ou componentes externos. Isso ajuda a entender o ecossistema no qual o sistema se insere.

• Estado atual da arquitetura: descrição do estado atual da arquitetura do sistema, incluindo suas principais funcionalidades e capacidades. O uso de diagramas pode ser particularmente útil para visualizar a estrutura do sistema.

• Requisitos não funcionais: descrição do desempenho, escalabilidade, segurança e outros requisitos não funcionais do sistema.

• Descrição detalhada da arquitetura: descrição detalhada da arquitetura do sistema, incluindo diagramas e descrições dos componentes e suas interações.

• Decisões arquitetônicas: descrição das principais decisões arquitetônicas e as razões por trás delas. Isso inclui restrições e justificativas para a escolha de soluções específicas em detrimento de outras.

• Instruções de instalação, configuração e operação: informações práticas sobre como instalar, configurar e operar o sistema. 

Conclusão – Maximizando a Compreensão do Código através da Documentação

É fundamental destacar a importância da manutenção contínua da documentação, garantindo que esta reflita sempre o estado atual do código. Documentação desatualizada, incorreta ou imprecisa pode acarretar confusão e problemas significativos durante o desenvolvimento e manutenção do software.

Além de ser uma prática essencial para o projeto e para a equipe envolvida, a atividade de documentação também enriquece o conhecimento do desenvolvedor sobre o código. Para criar uma documentação eficaz, é necessário sintetizar com precisão o que está sendo desenvolvido. Portanto, a documentação adequada exige uma compreensão profunda do código, do projeto como um todo e das interações entre os diversos serviços dentro do software.