Qual é o termo correto para a documentação que colocamos um pouco acima uma declaração de método?

Question

Eu estou escrevendo um whitepaper e percebi que eu não sei o que o termo oficial é para o tipo de documentação interna que nós colocamos como um bloco de comentário antes de uma declaração de definição.

A mesma coisa que eventualmente se torna documentação membro do JavaDoc.

Não é documentação simplesmente interna, e eu não tenho certeza "documentação cabeçalho" seria um termo bom.

Note que eu estou procurando um termo geral, não um específico para um determinado idioma (por exemplo, Java / Perl)

Answer 1

Isso é chamado de método de especificação ou procedimento especificação . Ou seja, ele especifica o comportamento do procedimento em vez dos detalhes de implementação. Alguns livros de texto referem a ele como o contrato do método, mas que pode ser um pouco ambígua.

Answer 2

Na minha organização podemos chamá-lo um método ou função doc-comment. documentação de nível de função é provavelmente o termo mais amplamente utilizado.

Answer 3

Eu sempre chamá-lo de método (ou função) comentário, para distingui-lo de classe ou arquivo comentários.

Answer 4

É muitas vezes profissionalmente referido como uma "cláusula de requisitos", ou uma "cláusula de seguro".

Answer 5

I geralmente se referem a ele como "documentação em linha." Para mim, isso é o que se trata - o fato de que a documentação é em seu código-fonte, por isso há mais de uma chance a documentação vai ficar em sincronia com o código

.

(Este não é garantia, é claro, mas não incentivar os programadores para comer seus legumes. Isso significa que o desenvolvedor pode alterar a documentação ao mesmo tempo e no mesmo lugar as mudanças de comportamento, ao invés de após o fato e em outro lugar.)

Answer 6

Eu chamo-lhe comentários de código, simples assim.