應該記錄API的所有公共方法嗎？

Question

在編寫「庫」類型類時，是否最好總是在java中編寫標記文檔（即javadoc），或者假設代碼可以是「自動記錄」的？例如，給出下面的方法存根：

/** 
* Copies all readable bytes from the provided input stream to the provided output 
* stream. The output stream will be flushed, but neither stream will be closed. 
* 
* @param inStream an InputStream from which to read bytes. 
* @param outStream an OutputStream to which to copy the read bytes. 
* @throws IOException if there are any errors reading or writing. 
*/ 
public void copyStream(InputStream inStream, OutputStream outStream) throws IOException { 
    // copy the stream 
} 

的Javadoc似乎是不言而喻的，而且只需要如果funcion在所有改變爲更新的干擾。但關於沖洗和不關閉流的話可能很有價值。

因此編寫庫時，是最好的：

一）始終記錄
二）文檔任何不明顯
C）從來沒有記錄（代碼應該爲自己說話）

！

我通常使用b），我（因爲代碼可以自我記錄，否則）...

Answer 1

我說，因爲當有人誰是鈍正在審查或修改代碼，什麼都不是即使沒有文件，你也會這樣認爲這很清楚。

Answer 2

a）始終記錄。

這將允許您使用自動化工具生成基於Web的基於紙張的文檔等，這對於那些始終沒有源代碼的用戶來說可能是非常寶貴的。

Answer 3

我選擇一個，純粹是因爲當我調查一個類時，我喜歡看到記錄的公共方法（在javadoc或類似的）。它使一些事情變得更清晰。但每一個都是屬於自己的。

Answer 4

每個應該記錄公共方法。

Answer 5

這就是我通常會在「我小時候雙向上坡」時吟誦的咒語，只有當你的老闆向你要求時才記錄下來，但是......最近我改變了我的曲調。我認爲這是至關重要當您正在開發一個開源項目，一個常用庫，或者提前知道其他人將不得不與您的接口密切合作時，提供每種公共方法的詳細文檔正在提供。文檔爲可維護的代碼提供了保證，但是和其他任何軟件一樣，當你需要增加功能並通過單元測試時，你可以花時間寫作註釋和POD和維基。這在Agile Manifesto中得到了解決（即：面對面的溝通比文檔更好，接口方法也是如此）。

Answer 6

一）

如果它是一個方法，總有一些事一些小細節，比如你提供關於沖洗和關閉流的人。例如，一個「String getFileExtension（String filename）」方法似乎不需要文檔，但是如果「filename」沒有擴展名？應該記錄答案。

如果它是一種類型，它應該提及它與之協作的其他類型，以及它是如何做到的。這有助於用戶按照自己想要的方式導航文檔，而不是無任何指導地瀏覽文檔。

Answer 7

一）

正如其他人所說，你可以生成文檔，並將它與維護有助於。

此外，Intellisense從告訴方法/屬性的功能中受益。

Answer 8

一）

的先期完整的文檔是幫助防止隨時間變化的方法，行爲改變一個額外的好處。在這個例子中，你引用了關於沖洗的句子，而不關閉流可能是有價值的 - 我會說這個級別的細節是方法的用戶需要知道的基本語義。如果沒有記錄，那麼稍後API的實現可能不會執行刷新，這可能導致該方法的用戶不可預測的結果。

Answer 9

特別是對於API，每個公共方法（和字段）都應該被記錄下來。此外，該方法的文檔應該足夠清楚和足夠豐富，以便可用的信息不留歧義。

API的一個很好的例子是Java API Specification。來自文件標題的通知是規範。我認爲文檔應該足夠徹底，可以將其作爲規範來考慮。

大多數情況下，我將Java API規範看作是一個很好的例子，但是，我注意到有一些部分沒有很好的文檔記錄和/或提供信息。以DropTarget班爲例。它有一個叫做clearAutoscroll()方法，以及該方法的Javadoc：

clearAutoscroll

protected void clearAutoscroll()

clear autoscrolling 

沒有什麼比文檔更令人沮喪的是無信息的API喜歡這個。最糟糕的是，所提供的信息甚至不是一句話！確保爲所有公共字段和方法提供的文檔足夠豐富，以至於圖書館的用戶不會感到惱火，而不會被告知。

Answer 10

所以，我的意見是，如果你正在開發一個API，供其他人使用，它應該能夠清楚每個方法，屬性的意圖等

我應該能夠看到一個方法和知道：

• 它返回什麼，如果有的話，如果返回值是在一個特定的單位（英尺，米，度等），那麼它應該清楚。用戶應該猜測你的方法是否返回攝氏或華氏或開爾文。
• 什麼參數需要和什麼單位的都在，如果該方法的任何
• 目的和範圍對這些參數和返回值，如果是有道理的
• 其他任何不明顯的讀者

作爲很多API的用戶，我已經看到了好的，壞的和醜陋的。作爲很多作家，我在早期就學到了關於提供接口時不清楚和具體的教訓，特別是當我不得不使用我幾年前寫的一個庫時，必須深入研究代碼以確定我究竟是什麼我在寫這本書時正在想。

我不認爲你需要在文檔上過度使用，並認爲精心挑選的方法，參數名稱等可以長時間讀取。但是當你寫一個方法的時候，只需要幾秒鐘 - 也許一分鐘就能完成 - 記錄下來。沒有令人信服的理由，我可以看到不公開接口，並將其記錄在需要它的地方。也許如果它是一個「一擲千金」的圖書館......但我不會寫太多的圖書館。

只是我的兩分錢。

Answer 11

任何可公開訪問的東西，無論是方法，字段，常量還是什麼都應該記錄下來，以便用戶或開發人員（這是一個包容性或btw）能夠在幾年後出現，並擁有他們需要的所有信息來利用記錄的對象。記錄使用的先決條件，目的，拋出的內容以及使用後的更改。

要清楚具體，不要留下任何猜測。如果您非常喜歡，請向沒有參與項目的人員展示您正在記錄的內容的聲明，並詢問他們是否缺少任何內容。做筆記，並確保涵蓋他們的顧慮。

Tout le monde說，代碼應該足夠好，但這是一個神話。並不是每個人都能看到代碼，或者意識到你在其中工作的巧妙技巧。因此，記錄其他人可能看到的所有內容，甚至記錄他們不會看到的內容。您的用戶，開發人員和您在幾年內都會感謝您。

Answer 12

總是記錄。

什麼是顯而易見的，你可能不是很明顯給其他人，特別是如果他們是從一個不同的角度看情況（非編碼器，初學者，用戶不熟悉你的語言結構）

而且爲了文件的完整性。

Answer 13

對不起鸚鵡，但總是文件。

始終記錄，甚至您的私人功能。我已經忘記了我多次認識的一切。但是一開始我對所有的東西都進行了評論，至少這很容易再次發現。當我創建了一些小型圖書館時，我記錄了我所在團隊的所有功能，但沒有提供我所做的一些筆記，內部工作將無法破譯。

我寫了一些荒謬複雜的代碼，以至於我的隊友都無法理解。沒有人認爲它馬虎或不雅，但在詳細解釋（花費幾個小時）之前，沒有人可以遵循邏輯。我在紙上寫過一次後，這似乎是對我的明顯答案，但在這個問題上，我的邏輯對其他人來說是陌生的。

因此，我掃描了論文，記錄了我的所有功能，並列出了所需的所有輸入格式，並撰寫了關於應用程序如何完成其​​任務的額外文檔。我放棄了超過3年的這份工作，當他們需要某些特定的東西時（最近6個月前），我仍然談論這個軟件。它不及Kloc（1000行代碼），但它仍然足夠複雜，足以在2年半後提出問題。

Answer 14

b）記錄所有不明顯或有疑問的事情。在這種情況下：

/** Copies all readable bytes from inStream to outStream. outStream will be flushed, 
* but neither stream will be closed. 
*/ 

你已經寫了inStream中是一個InputStream，你不必指定它打算在其自己的註釋要讀取的字節，因爲你已經在函數的評論

這樣做

Answer 15

只記錄您希望人們能夠使用並有效使用的方法。