O que devo incluir no cabeçalho da documentação da minha classe

Estou procurando um formato informativo de documentação de classe para minhas classes de Entidade, Lógica de negócios e Acesso a dados.

Encontrei seguindo dois formatos daqui

Formato 1

///-----------------------------------------------------------------
///   Namespace:      <Class Namespace>
///   Class:          <Class Name>
///   Description:    <Description>
///   Author:         <Author>                    Date: <DateTime>
///   Notes:          <Notes>
///   Revision History:
///   Name:           Date:        Description:
///-----------------------------------------------------------------

Formato 2

// ===============================
// AUTHOR     :
// CREATE DATE     :
// PURPOSE     :
// SPECIAL NOTES:
// ===============================
// Change History:
//
//==================================

Eu sinto a seguir são os elementos básicos

• Autor
• Data de criação
• Descrição
• Histórico de Revisão

como Namespace e Class name estarão lá de qualquer maneira.

Deixe-me saber sua opinião, qual formato é recomendado e se existe uma maneira padrão de escrever o histórico de revisões?

A maioria das informações que você sugeriu seria encontrada no repositório de origem.

A única coisa que você realmente precisa é da seção de propósitos, que diz para que serve a classe.

Seria tedioso procurar no repositório toda vez que você quiser conhecer as outras informações? Eu diria que não. Com que frequência você se importa com quem foi o autor original? Ou quando o arquivo foi criado pela primeira vez? Os plug-ins (como o Ankh SVN para Visual Studio) geralmente permitem clicar com o botão direito do mouse no arquivo atual e exibir o log de repositório do arquivo, portanto, não é tão complicado ver essas informações.

Além disso, se você armazenar o histórico da versão em um comentário, esse comentário precisará ser mantido. Então, com o tempo, há uma chance de que isso esteja mentindo para você. O repositório de código-fonte mantém automaticamente esses dados históricos, portanto não precisa dessa manutenção e será preciso.

Tenha nomes de classe, método e variável descritivos . Isso eliminará a necessidade de comentários como objetivo e descrição. Às vezes, pensamos que quanto menor o nome do método, melhor. Pelo contrário, crie um nome de método pelo tempo que desejar, desde que ele descreva claramente sua finalidade. Tenha apenas notas absolutamente vitais e ajude a codificar a compreensão de alguma maneira específica. Ao fazer alterações no código, os programadores geralmente esquecem de atualizar os comentários. Você pode acabar com os comentários e o código fora de sincronia e fazendo mais mal do que bem.

Leia este artigo por Jeff Atwood - Codificação sem comentários .

Eu uso tags padrão para gerar documentação. Nada mais nada menos. Veja aqui

Eu nunca coloco informações que não pertencem à classe. Autor, dados, revisões são dados para armazenar em um sistema de controle de versão.

Os dois formatos apresentados são inúteis para gerar documentação e apresentam o maior erro nos comentários, eles listam o histórico de revisões.

Muitas dessas informações podem ser adicionadas pelo seu repositório de controle de origem, deixando você realmente apenas com a descrição, que deve descrever com precisão o escopo e o comportamento da classe. Eu recomendo dar uma olhada em alguns dos Javadoc para o Java JDK como um exemplo.

Tudo nessa lista é desnecessário. Seu controle de origem deve cuidar de quase tudo, e o que ele não cobre é tratado por boas convenções de nomenclatura.

Se eu tiver que ler sua "Descrição" para descobrir o que sua classe está fazendo, então (a) o nomeou mal ou (b) você escreveu uma classe ruim que está fazendo muito (SRP).

Venho brincando com a alteração dos meus modelos de cabeçalho, pois, como outros apontam, muitas dessas informações podem ser encontradas no repositório e até agora os grandes campos que tenho procurado manter são os seguintes:

• Descrição - O que está sendo feito pelo código.
• Notas - Qualquer coisa que precise ser conhecida sobre o código que não seja facilmente derivada dos comentários no próprio código.
• Referências - Quaisquer referências que dependem do código que não sejam esclarecidas pelo uso de includeou instruções semelhantes.

Um item que também pode ser útil incluir é uma seção sobre Palavras - chave Embora você possa pesquisar nomes de funções, classes, estruturas, etc., pode haver algumas palavras-chave que os outros nomes no arquivo não deixam claro. Ou, para códigos mais antigos e mal documentados, pode ser a primeira etapa na documentação do código para manutenção.

A maioria das outras respostas que li até agora pressupunha que há apenas um repositório sempre disponível

Como o código-fonte pode perder a conexão com o repositório (ou seja, se copiado), a documentação da minha classe é assim:

• class documentation header (= o bloco de comentários no início do arquivo) contém apenas informações legais necessárias (ou seja, direitos autorais de xyz sob licença gpl)
• tudo o que um desenvolvedor que usa a classe deve saber deve entrar na classe-java-doc-comments (ou o equivalente .net dela) para que os ide-s modernos possam mostrar essas informações como informações da dica de ferramenta no código-fonte que usa a classe.

Você também pode adicionar o número do ticket para a correção de bug ou solicitação de recurso, para ter uma idéia de onde / quando / por que a classe foi criada (se você tiver sorte o suficiente, ainda poderá acessar os tickets depois de alguns anos).

Quando me pedem para corrigir problemas nos antigos programas legados de código fechado, os números dos tickets são bastante valiosos para eu entender os requisitos originais do código.