Comentários
- Por favor, especifique qual idioma você deseja documentar, os padrões e ferramentas variam entre os idiomas .
- Comece com isto: O que seu software deveria resolver / fazer? Documente as etapas de como ele faz isso em primeiro lugar.
- Encontre o código existente em projetos de código aberto existentes. Por favor, leia o código existente. Em seguida, compare-o com o seu. Finalmente, depois de fazer isso, faça perguntas específicas com base no código que você encontrou.
Resposta
Você deve documentar:
- a intenção, o porquê;
e
- o que pode não seja óbvio, o como.
Por que você otimizou este bit, para que exatamente é esse atalho, qual é o resultado que você espera, qual é o requisito, a razão para ele estar lá em primeiro lugar, para onde esses dados são enviados, de onde você obtém a entrada, se for multi-threaded, explique o modelo, se houver um banco de dados, explique o esquema, os links, por que …
Não documente o óbvio. Quanto à apresentação, há muitas maneiras de fazer isso. Pessoalmente, gosto de comentários embutidos (sou um tipo de programador mais antigo e não tínhamos ferramentas sofisticadas naquela época – além disso, apenas encontre-o simples e direto). Se você quiser algo sofisticado, certifique-se de que não consuma muito do seu tempo ou você provavelmente irá abandoná-lo em breve.
Comentários
- A intenção é geralmente a coisa mais útil, posso olhar para o código e entender o que ele faz, mas entender por que o desenvolvedor fez dessa forma pode ser muito útil.
Resposta
Leia um pouco do seu próprio código que escreveu há 2 ou mais anos.
Pergunte a si mesmo que tipo de coisas não estão claras e o deixam com a cabeça coçando após a leitura. Esses tipos de coisas (sejam eles quais forem, serão diferentes para diferentes programadores) é o que você deseja começar a documentar primeiro em qualquer código novo que você desenvolver ou código antigo que você reescrever / reutilizar. Qualquer formatação que retarde sua compreensão , mude.
Ou então, em 2 anos …
Resposta
Uma coisa que você deve incluem as dependências. Se uma função depende de algo ali , então doc ument o que é, onde ali está, e por quê.
Resposta
Visto que você está usando PHP, PHPDoc seria um bom lugar para começar. Você pode criar a documentação da API in-line no código-fonte e, em seguida, usar o mesmo formato para escrever tutoriais e documentação do usuário. Você também obterá alguma flexibilidade no que diz respeito ao formato de saída.
Resposta
Eu sempre começo a escrever o código escrevendo meus comentários primeiro. Descreva o fluxo do programa e você começará a perceber o que precisa ser comentado e o que não. Depois de começar a escrever o código, você embeleza as partes que precisam de explicação adicional e refina as partes que são autodocumentadas.
Depois que cada classe, função ou método estiver concluído, volto e adiciono comentários para um gerador de documentos como doxygen ou PHPDoc. Isso fornecerá a documentação da API real.
Dependendo de quem consome meu código, escreverei uma descrição formal do documento de operação em LaTeX ou Word.
Resposta
O Doxygen cobre a maioria dos idiomas. Você terá que gastar algum tempo para entender a sintaxe, mas o grande problema é o que documentar. Trate cada função como uma caixa preta. Documente o que entra e o que sai. Documente quais erros ele intercepta, se args pode ser nulo, se pode retornar um nulo.
Lembre-se, em apenas alguns meses você não será capaz de descobrir o que diabos uma função faz. Você está apenas economizando tempo.