Qual é o termo correto para a documentação que colocamos um pouco acima uma declaração de método?
-
03-07-2019 - |
Pergunta
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)
Solução
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.
Outras dicas
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.
Eu sempre chamá-lo de método (ou função) comentário, para distingui-lo de classe ou arquivo comentários.
É muitas vezes profissionalmente referido como uma "cláusula de requisitos", ou uma "cláusula de seguro".
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.)
Eu chamo-lhe comentários de código, simples assim.