Não
Está bem. Obviamente, estou brincando. Bem, meio brincando, pelo menos.
Tudo apodrece. Documentação podre nunca é uma boa documentação, mesmo que tenha começado assim. O conteúdo de seus projetos apodrecerá nesta ordem:
- Documentação
- Readme’s
- Comentários
- Código
A documentação externa é quase inútil depois de muito tempo; Portanto, não escreva. Ter documentação ruim é pior do que não ter documentação. Um desenvolvedor confuso é muito mais perigoso do que um desenvolvedor que não tem certeza de algo.
Há coisas que precisam ser documentadas, mas não pense nelas como documentação. Se você tem uma camada de API, deve escrever uma folha de especificações. E quero dizer fazer isso antes de implementar sua API. Claro que vai mudar, então atualizei. Mas uma vez que sua API está bloqueada, você não precisa se preocupar em mudar sua planilha. Pontos de bônus por usar documentação gerada como Swagger
Nota lateral: E pelo amor de Deus, use dogfood para sua API!
Os leia-me podem ser importantes, eles ganham o benefício de serem mais fáceis de alterar, já que estão no repositório (e, com sorte, são remarcados). Sempre que vejo algo documentado em Word ou PDFs, fico preocupado (e choro). Quanto maior o custo da mudança, menos ele será alterado. O Leiame deve realmente incluir coisas abstratas e como colocar o projeto em execução. Evite detalhes de implantação, qualquer coisa que possa mudar.
Arquivos CHANGELOG e TODO podem ser bons, mas apenas se você se lembrar de atualizá-los. Existem maneiras de gerar changelogs de git e todo’s de comentários. Prefira isso ao manual.
Como regra, não comente seu código. Se você tiver que comentar seu código, você deve reescrever / refatorar seu código para que fique claro o que está acontecendo. Isso irá melhorar a capacidade de manutenção dos seus códigos e remover a podridão de comentários. Vencer / Vencer. O código autodocumentado é praticamente a única coisa que sobreviverá ao teste do tempo em qualquer projeto.
- Os namespaces devem descrever o contexto
- As aulas devem descrever os recursos
- As funções devem descrever as ações.
- Funções auxiliares devem descrever ações simples.
- Parágrafos (ou blocos) de código devem ser de um único pensamento.
- Frases (ou linhas) de código devem fazer uma única coisa. [Se eu tiver que pensar sobre a ordem das operações, você está fazendo errado]