Was ist der richtige Begriff für die Dokumentation, die wir über eine Methode Erklärung setzen?

Question

Ich schreibe ein White Paper und erkennen, dass ich nicht sicher bin, was die offizielle Bezeichnung für die Art der internen Dokumentation, die wir als Kommentarblock vor Erklärung der Definition setzen.

Das gleiche, was schließlich JavaDoc Mitglied Dokumentation wird.

Es ist nicht einfach die interne Dokumentation, und ich bin mir nicht sicher „Header-Dokumentation“ ein guter Begriff sein würde.

Beachten Sie, dass ich mich für einen allgemeinen Begriff suche, nicht ein spezifisch für eine bestimmte Sprache (beispielsweise Java / Perl)

Answer 1

Dies ist eine Methode Spezifikation oder Verfahren Spezifikation genannt. Das heißt, es gibt das Verhalten des Verfahrens und nicht die Details der Implementierung. Einige Text Bücher beziehen sich auf ihn als den Vertrag des Verfahrens aber das kann ein bisschen zweideutig sein.

Answer 2

Bei meiner Organisation, die wir nennen es eine Methode oder Funktion doc-Kommentar. Funktionsebene Dokumentation ist wahrscheinlich der am meisten benutzte Begriff.

Answer 3

Ich nenne es immer Methode (oder Funktion) Kommentar, es von Klasse zu unterscheiden oder eine Datei Kommentar.

Answer 4

Es wird oft professionell bezeichnet als „Anforderungen Klausel“ oder eine „Versicherungsklausel“.

Answer 5

ich in der Regel auf sie als verweisen „Inline-Dokumentation.“ Für mich ist das, worum es geht -. Die Tatsache, dass Ihre Dokumentation ist in Ihren Quellcode, so dass es eher eine Chance, die Docs synchron mit dem Code bleiben

(Dies ist keine Garantie, natürlich, aber es Programmierer ermutigen, ihr Gemüse zu essen. Es bedeutet, dass die Entwickler die Dokumentation ändern können zur gleichen Zeit und an der gleichen Stelle die Verhaltensänderungen, anstatt nach der Tat und an einem anderen Ort.)

Answer 6

Ich nenne es Code Kommentare, einfach so.