ti-enxame.com

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 dois formatos a partir de aqui

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:
//
//==================================

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?

15
CoderHawk

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

A única coisa de que você realmente precisa é a seção de propósito, 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 que você clique com o botão direito do mouse no arquivo atual e visualize o log de repositório do arquivo, portanto, não é tão trabalhoso 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.

27
David_001

Tenha nomes descritivos de classe, método e variável . 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 descreva claramente sua finalidade. Tenha apenas anotações 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 .

14
ysolik

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.

5
Maniero

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 Javadoc para o Java JDK como exemplo.

3
Martijn Verburg

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).

3
Chris Holmes

Eu tenho brincado em mudar 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 eu 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 include ou instruções semelhantes.

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

2
rjzii

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), minha documentação de 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 da 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 em programas antigos de código fechado, os números dos tickets são bastante valiosos para eu entender os requisitos originais do código.

1
k3b