Aquarela

Aquarela Analytics branco

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

documentação de código

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.

Quem é a Aquarela Analytics?

A Aquarela Analytics é vencedora do Prêmio CNI de Inovação e referência nacional na aplicação de Inteligência Artificial corporativa na indústria e em grandes empresas. Por meio da plataforma Vorteris, da metodologia DCM e o Canvas Analítico (Download e-book gratuito), atende clientes importantes, como: Embraer (aeroespacial), Scania, Grupo Randon (automotivo), SolarBR Coca-Cola (varejo alimentício), Hospital das Clínicas (saúde), NTS-Brasil (óleo e gás), Auren, SPIC Brasil (energia), Telefônica Vivo (Telecomunicações), dentre outros.

Acompanhe os novos conteúdos da Aquarela Analytics no Linkedin e assinando a nossa Newsletter mensal!

Deixe um comentário

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *

Send this to a friend