Você deve documentar tudo ou apenas a maioria?

Parece um assunto controverso documentar tudo, incluindo a sintaxe "JavaBean" de getters e setters para campos: as pessoas dizem que é DRY desnecessariamente longo e repetitivo (não se repita) , que a convenção de nomenclatura deve explicar tudo , e confunde código / documentação. Às vezes, esses argumentos funcionam. Mas outras vezes, você acaba com isso:

Acima é comum projetos de código aberto que seguem corajosamente esses princípios. Você fica com uma documentação totalmente inútil . Isso não explica nada sobre o que está acontecendo por baixo, os possíveis efeitos ou mesmo qual é o valor esperado (poderia ser nulo ou nunca nulo? Eu não sei; o Javadoc não me diz).

Então, quando devo documentar? Documento tudo, mesmo que ocasionalmente desorganize o código? Ou não documento nada, pois, aos meus olhos, é "óbvio"?

Documente tudo o que faz sentido para documentar .

Em um mundo ideal, sim, você documentaria tudo. No entanto, na Terra, temos prazos, cortes de recursos, famílias e amigos para visitar, férias para tirar, apenas 24 horas por dia e apenas 365 dias em um ano. Simplesmente não há tempo suficiente para documentar tudo. Portanto, otimamente, documente tudo o que puder (não será feito), mas obtenha o máximo de retorno possível:

• Torne o código legível e as assinaturas de método o mais óbvio possível, para que a documentação seja menos provável .
• Documentando as coisas mais obscuras primeiro. Ajude outras pessoas documentando os truques malucos que você tinha que fazer para obter as coisas pela porta.
• Documente o porquê antes do quê - Não comente o que algo faz, como "Itere sobre os registros do cliente em que o saldo é menor que zero e a classificação é menor que um e adicione-os à lista de clientes isentos". Documente por que você os está adicionando à lista em inglês simples (ou no idioma da sua equipe), como "Como esses clientes têm um saldo negativo e classificações baixas, eles estão nos causando a perda de dinheiro, portanto, exclua-os de fazer o check-out.

Continue documentando até poder ver alguém lê-lo sem sentir a necessidade de explicar nada.

Na semana passada, houve um ótimo artigo sobre documentação no The Daily WTF. Eu acho que diz tudo, então vou deixar o link:

http://thedailywtf.com/Articles/Documentation-Done-Right.aspx

Basicamente, ele diz que você não deve documentar algo se não for útil (alguma documentação é deixada para apodrecer em uma gaveta) e documentar a menor quantidade de informações necessárias para entender uma determinada parte do projeto. Muita documentação apenas confunde o leitor.

Realmente depende de quão legível o código é para o público que o lê. Descubra quem é o público lendo seu código e peça a alguém que atenda a esse perfil que leia seu código.

Outra abordagem seria revisar seu próprio código depois de uma semana e ver se você ainda entende o que fez, se não, documentar e revisar o código em duas semanas ou mais.

Embora aprecie uma documentação clara e extensa, não há nada como código de auto-documentação. Então, o resultado final (para mim) é:

Suspeite muito da documentação (código fonte); tente torná-lo redundante melhorando o código, mas não evite documentar clara e completamente quando necessário.

Obviamente, sob certas circunstâncias, a documentação pode ser necessária por outros motivos além de 'explicar o que o código está fazendo' (por exemplo: grande equipe, padrões de organização e assim por diante).

Minha sugestão na documentação é que, se houver algo sofisticado no código, isso pertence a um documento que deve ser mantido atualizado. Gosta de estar sujeito a muita interpretação; na minha opinião, é onde algo é feito de uma maneira específica que pode ter efeitos colaterais que devem ser observados; por exemplo, algo pode ser feito de forma recursiva para garantir que os itens netos sejam processados ​​ao passar por uma árvore de nós para realizar algum teste em todos os descendentes. Articular por que algo foi feito de uma maneira específica pode ser uma boa maneira de saber se havia ou não um bom motivo para usar alguma coisa.

Em termos simples, a documentação existe para ajudar os desenvolvedores agora e os mantenedores no futuro.

Se você se lembrar dessa máxima simples, o nível de documentação deve ser autodefinido.

A documentação, por uma questão de documentação, é uma perda de tempo ... mas explicar hoje o que você está fazendo é mais útil do que alguém que precisa fazer engenharia reversa do seu código em cinco anos.

Pessoalmente, eu vou com a abordagem de considerar documentar tudo. Ou seja, durante a codificação, considero em todos os pontos se a documentação agregaria valor. Na maioria das vezes, a resposta é sim para exatamente os tipos de restrições e conhecimentos de domínio mencionados na pergunta original. Por exemplo, capacidade nula, restrições únicas, interpretação do campo no domínio mais amplo.

Para evitar duplicação, eu tendem a documentar fortemente as principais classes de API com esse tipo de informação. Documente apenas implementações e componentes internos onde houver comportamento não óbvio ou inconsistente. Acho que isso funciona bem, pois são os usuários da API que precisam de mais ajuda e documentação. Geralmente, é seguro assumir que as pessoas que modificam a implementação conhecem a API e têm esse conhecimento.

Eu também tendem a documentar apenas os getters. Não duplico a documentação em setters, definições de campos e parâmetros de construtores. Apenas documento comportamentos não óbvios, como padrões nesses locais. Qualquer comportamento que possa ser deduzido da documentação do getter não está documentado. Por exemplo, se o getter estiver documentado como nulo que nunca retorna, geralmente não documento que você não pode passar nulo ao setter, a menos que haja um padrão.

Algumas pessoas gostam de marcar esse ato de "considerar a documentação" adicionando comentários vazios onde consideraram a documentação, mas a consideraram desnecessária. Eu não gosto dessa prática, pois apenas confunde o código e atrapalha.