我們在方法聲明之上放置的文檔的正確術語是什麼？

Question

我正在寫一篇白皮書，並且意識到我不確定我們在定義聲明之前將哪些內部文檔作爲註釋塊使用的官方術語。

最終成爲JavaDoc成員文檔的相同事物。

這不僅僅是內部文件，我不確定「頭文件」是一個好的術語。

請注意，我在尋找一個通用術語，而不是一個具體的特定語言（例如，Java/Perl的）

Answer 1

這被稱爲方法規範或規程。也就是說，它指定了過程的行爲而不是實現細節。一些教科書將其稱爲該方法的合同，但這可能有點模糊。

Answer 2

它通常專業被稱爲「要求的條款」，或「保險條款」。

Answer 3

在我的組織中，我們稱之爲方法或功能doc評論。功能級文檔可能是更廣泛使用的術語。

Answer 4

我總是將它稱爲方法（或函數）註釋，以區分它與類或文件註釋。

Answer 5

我把它稱爲代碼註釋，就像那樣簡單。

Answer 6

我通常將其稱爲「內聯文檔」。對我來說就是這樣 - 事實上，你的文檔是，你的源代碼是，所以文檔將會更多地與代碼保持同步。

（這是不能保證的，當然，但它確實鼓勵程序員吃的蔬菜。這意味着開發人員可以在同一時間和在同一個地方改變文檔行爲的變化，而不是事後在另一個地方。）