¿Cuál es el término correcto para la documentación que colocamos justo encima de una declaración de método?

Question

Estoy escribiendo un documento técnico y me di cuenta de que no estoy seguro de cuál es el término oficial para el tipo de documentación interna que ponemos como bloque de comentarios antes de una declaración de definición.

Lo mismo que eventualmente se convierte en documentación de miembro de JavaDoc.

No es simplemente documentación interna, y no estoy seguro de que " documentación de encabezado " sería un buen término.

Tenga en cuenta que estoy buscando un término general, no uno específico para un idioma en particular (por ejemplo, Java / Perl)

Answer 1

Esto se denomina especificación del método o especificación del procedimiento . Es decir, especifica el comportamiento del procedimiento en lugar de los detalles de la implementación. Algunos libros de texto se refieren a él como el contrato del método, pero eso puede ser un poco ambiguo.

Answer 2

En mi organización lo llamamos método o función doc-comment. La documentación de nivel de función es probablemente el término más utilizado.

Answer 3

Siempre lo llamo comentario de método (o función), para distinguirlo de los comentarios de clase o archivo.

Answer 4

A menudo se lo conoce profesionalmente como una " cláusula de requisitos " ;, o " cláusula de seguros " ;.

Answer 5

Normalmente lo llamo " documentación en línea. " Para mí de eso se trata: el hecho de que su documentación esté en su código fuente, por lo que es más probable que los documentos se mantengan sincronizados con el código.

(Esto no es una garantía, por supuesto, pero alienta a los programadores a comer sus vegetales. Esto significa que el desarrollador puede cambiar la documentación al mismo tiempo y en el mismo lugar el comportamiento cambia, en lugar de después del hecho y en otro lugar.)

Answer 6

Lo llamo código de comentarios, así de simple.