Quel est le terme correct pour la documentation que nous mettons juste au-dessus d'une déclaration de méthode?

Question

J'écris un livre blanc et je me suis rendu compte que je ne suis pas sûr du terme officiel qui désigne le type de documentation interne que nous mettons en bloc de commentaires avant une déclaration de définition.

La même chose qui finit par devenir la documentation des membres JavaDoc.

Il ne s'agit pas simplement d'une documentation interne, et je ne suis pas sûr de la "documentation en-tête". serait un bon terme.

Notez que je recherche un terme général, et non spécifique à un langage particulier (par exemple, Java / Perl)

.

Answer 1

Cette opération est appelée spécification de méthode ou spécification de procédure . Autrement dit, il spécifie le comportement de la procédure plutôt que les détails de la mise en œuvre. Certains manuels y voient le contrat de la méthode, mais cela peut paraître un peu ambigu.

Answer 2

Dans mon organisation, nous l'appelons une méthode ou fonction doc-comment. La documentation au niveau fonctionnel est probablement le terme le plus largement utilisé.

Answer 3

Je l'appelle toujours comment méthode (ou fonction), afin de le distinguer des commentaires de classe ou de fichier.

Answer 4

Il est souvent qualifié par les professionnels de "clause d'exigence" ou de "clause d'assurance".

Answer 5

Je parle généralement de "documentation en ligne". Pour moi, c’est de ça qu'il s'agit & # 8212; le fait que votre documentation soit dans votre code source, il est donc plus probable que les documents restent synchronisés avec le code.

(Ce n'est pas une garantie, bien sûr, mais cela encourage les programmeurs à manger leurs légumes. Cela signifie que le développeur peut modifier la documentation en même temps et au même endroit le comportement change plutôt qu’après les faits et ailleurs.)

Answer 6

Je l'appelle les commentaires de code, c'est simple comme ça.