Formato de comentário do cabeçalho

Sei que o formato "comentário do cabeçalho" varia de programador para programador, mas o que seria um exemplo de um comentário de cabeçalho "bom"?

— Mateen Ulhaq
fonte

Esta pergunta é apenas sobre formatação ou sobre estilo e conteúdo?

— Macneil 30/03

@ Macneil Depende do que eles significam. Por enquanto, vou jogar pelo seguro e dizer "ambos". :)

— Mateen Ulhaq 30/03

Em relação ao estilo de formatação, a consistência é mais importante. Verifique se todos os comentários de definição de classe se parecem com todos os outros, todos os comentários de método se parecem com todos os outros, etc.

Portanto, se você estiver modificando o código existente , siga o estilo de formatação. Os comentários (e, até certo ponto, o código) devem parecer que apenas uma pessoa trabalhou no arquivo. Se você estiver iniciando um novo projeto, escolha um formato de estilo e atenha-se a ele.

Locais para começar a procurar:

Guias de estilo do Google (C ++, JavaScript, Objective-C e Python)
Exemplo de comentário do Oracle JavaDoc

— JK
fonte