15

Gostaria de fazer minha pergunta com base nessa questão sobre testes.

Existem diferentes maneiras de documentar um software, as que mais observei são:

  • Documentação da classe (o desenvolvedor comenta qual o objetivo e/ou tarefa daquela classe)
  • Documentação do método (o desenvolvedor comenta qual o objetivo, ações e/ou tarefas que aquele método realiza)
  • Documentação dentro do código (o desenvolvedor comenta o que ocorre em determinada linha de código)
  • Documentação gerada de maneira automatizada a partir do Javadocs, por exemplo.

Portanto, baseando sobre algumas perguntas do link que mencionei acima:

  • Qual seria uma boa forma de documentar o software?
  • É interessante colocar documentação no código? É útil somente para desenvolvedores inexperientes em início de carreira ou também para desenvolvedores experientes que já tem domínio na linguagem? Pergunto isso porque já ouvi falarem que não precisa de documentação porque lendo o código você já sabe qual ação aquele trecho de código realiza. Porém pelo que observo a arquitetura do sistema tem a sua influencia, a maneira como o desenvolvedor desenvolveu aquilo, posso citar exemplo o conceito de MVC, Injeção de Dependência que possuem as suas arquiteturas, assim o desenvolvedor poderia criar uma arquitetura diferente para um padrão de projeto dentro da aplicação.
  • Existem critérios para tal?
  • Como base na melhor resposta da pergunta que mencionei sobre testes, dentro da documentação de sistemas existem descrições, como, por exemplo, Teste de Integração, Teste Unitário, Canary Release que foram mencionados na resposta? Porém nessa pergunta que criei referindo-se a documentação.
1
  • Geralmente documentação serve pra implementar uma nova funcionalidade ou alterar uma já existente.
    – Laerte
    Commented 23/10/2015 às 13:42

2 Respostas 2

18

Primeiro vamos diferenciar documentação e comentário. São coisas distintas com objetivos distintos e por isso tratamos de forma distinta.

E já vamos deixar claro que cada equipe sabe o que é melhor para ela em cada projeto. Há apenas algumas recomendações, experiências que costumam dar certo.

Documentação

Documentação da API, ou seja, as classes e os membros públicos, é bem interessante documentar, afinal alguém vai consumi-las em algum momento. Pode ser você mesmo que a criou, anos depois vai usar e não lembrar de como fazer. Melhor ter uma documentação dentro de um padrão estabelecido do que ter que ficar lendo o código para saber como usá-lo.

Embora isto costume estar junto do código, ele não faz parte do código propriamente dito. É bom estar perto para facilitar qualquer alteração quando o código altera. Se bem que mudanças no código não deveriam forçar mudanças na documentação. Mas isto já é outro assunto.

Há controvérsias se deve documentar formalmente métodos privados. A maioria dos programadores consideram que um comentário simples já é suficiente, ou mesmo nada quando o método é auto descritivo e não tem nada realmente útil que acrescente algo.

A documentação da arquitetura também é fundamental para qualquer pessoa entender como tudo funciona. Normalmente ela é separada completamente do código. São textos e diagramas explicativos de forma ampla.

Testes

Testes podem ser usados como forma de documentação alternativa. Mas eles não substituem um texto comum. Eles funcionam mais como uma documentação técnica mostrando como os componentes devem responder. Ao invés de dizer que um método sempre deve retornar um número positivo, você faz um teste que verifica se isto está sendo feito corretamente. Algumas linguagens possuem contratos que permitem isto no próprio código.

Comentários

Comentários devem ser usados especialmente quando o código não consegue expressar o que está acontecendo ou faz algo que não é muito intuitivo. Comentários servem para explicar porque está fazendo aquilo.

Comentários dizendo o que está fazendo beiram o ridículo e realmente só servem para ajudar novatos entenderem melhor o que está acontecendo, servem para aprender. São comentários didáticos que não devem ser usados em códigos em produção.

Na maior partes das vezes quando vemos comentários dizendo o que a linha faz, é redundante.

  • Está confuso?

    Torne mais simples.

  • Não deixa claro o que é aquilo?

    Dê melhores nomes.

  • Está destacando o bloco?

    Separe em métodos menores.

Dei uma resposta mais profunda sobre isto.

Dicas para aprender documentar

Procure ver como os bons projetos fazem a documentação e se inspire neles.

As ferramentas existentes hoje para ajudar formatar a documentação já dão dicas do que ela deve conter. Mas lembre-se de não falar de obviedades, além de não esquecer de informações importantes, especialmente quando pode provocar problemas ou comportamentos inesperados.

Coloquei no GitHub para referência futura.

1
14

Qual seria uma boa forma de documentar o software?

Depende de várias coisas, mas eu diria que, inicialmente, seria seguindo o padrão de projeto que a comunidade que desenvolveu o padrão recomenda.

Por exemplo, em Java temos o Javadoc. Em .NET temos o XML Documentation. Em Python temos um guia de boas práticas, e assim por diante.

Logo em seguida, poderia ser algum padrão de documentação que seja inerente à equipe que desenvolve. Quando não há equipe que desenvolve, pode ser algum padrão seguido pela comunidade em que o código fica. O GitHub, por exemplo, tem como hábito as documentações envolvendo o Markdown.

É interessante colocar documentação no código?

Sempre é. O que deve se evitar é prolixidade no código. Pessoalmente, tenho as seguintes premissas:

  • Não documentar trechos óbvios (obviedade é subjetiva, então documento o que minha consciência e meu bom senso dizem que é uma boa ideia);
  • Usar nomes de variáveis que indicam o que ela faz, sem contrações. Contrações de nomes de variáveis criam ambiguidades;
  • Escrever algo que o programador ganhe tempo, não que perca: sei que expressão não é pra todo mundo. Existem ótimos programadores com uma capacidade limitada de expressão, e que conseguem escrever comentários que mais atrapalham que ajudam. Ou seja, se o comentário deixado não ajuda, melhor retirá-lo.

É útil somente para desenvolvedores inexperientes em início de carreira ou também para desenvolvedores experientes que já tem domínio na linguagem?

Para todos, eu diria. Principalmente para os juniores. Considerando que a maior parte do universo de programadores é júnior, eu diria que é muito voltado pra eles.

Também é útil para programadores experientes. Não significa que um programador com alto grau de senioridade vá ler o código todo e entender tudo.

Existem critérios para tal?

Isto é um pouco subjetivo. Vou pela regra de ouro: É útil a informação? Documente.

2
  • 2
    se o comentário deixado não ajuda, melhor retirá-lo, igual aqui no SOpt!
    – brasofilo
    Commented 23/10/2015 às 16:18
  • Muito obrigado pela sua resposta, foi díficil escolher a melhor, as duas foram muito boas. Levei em consideração o número de votos até o momento. Commented 23/10/2015 às 17:28

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .