1. 首頁
  2. 問答
  3. 函數的註釋是否應該包含它調用的函數完成的工作描述？

函數的註釋是否應該包含它調用的函數完成的工作描述？

2009-12-05 17 views
0

假設我有一個名爲DisplayWhiskers（）的函數，它在屏幕上放置一些斜槓和反斜槓來表示動物的鬍鬚，如下所示：/// \\\。 我可能會寫沿函數的註釋是否應該包含它調用的函數完成的工作描述？

// Represents an animal's whiskers by displaying three 
// slashes followed by a space and three backslashes

行此功能註釋，但如果我再添加功能DisplayKitten（）和DisplaySealion（），它作爲關於顯示他們的工作電話DisplayWhiskers的）部分（多少細節的鬍鬚應該在這些其他功能的評論？

一方面，我應該可以查看DisplayKitten（）的評論，並瞭解我需要的所有內容，包括它將如何顯示鬍鬚。我不應該去其他地方閱讀DisplayWhiskers（）的評論來找出答案。另一方面，如果DisplayKitten（）的註釋明確指向三個斜槓，後面跟着三個反斜槓，這似乎違背封裝的精神，並且如果稍後更改DisplayWhiskers（），則可能會變得錯誤。

什麼被認爲是最佳實踐？

編輯：幾個答案都建議解決方案是讀取代碼。我理解好代碼的原則是它自己最好的評論，但是對於這個問題，我並不是要引用代碼內的註釋，而是要引用伴隨函數原型的頭文件中的註釋。讓我們假設實際的代碼是預編譯的，並且對於想要使用或調用它的客戶是不可訪問的。

來源

2009-12-05 pocketdora

+2

「看來我應該能夠查看DisplayKitten（）的註釋，並理解我需要的關於它將要執行的操作的所有信息。」你爲什麼要這個？這聽起來像是對我的評論濫用。如果您想了解DisplayKitten將要執行的操作，請閱讀代碼。 – mquander 2009-12-05 19:13:54

+0

對於它的價值，我完全不同意mquander。查看代碼是絕對的最後手段，只是證明你沒有正確定義接口。 DisplayKitten必須展示一隻小貓。如果每個人都開始「只是閱讀代碼」，並依靠實現細節甚至可能是錯誤，而不是假設他們會得到一隻小貓，那麼您將永遠無法再改變該代碼的一行而無需遵循它遍佈整個代碼庫。在一個組件當然，你可以放鬆一點關於封裝，但它對大型項目是至關重要的。 – 2009-12-05 21:31:03

+0

所以：你應該記錄一隻小貓有六隻鬍鬚，如果（而且只是）你想要和呼叫者需要依靠那個。否則，不要證明小貓有六隻鬍鬚，任何假設小貓有六隻鬍鬚的呼叫者只是因爲他讀了你的代碼應該被認爲是惡意的破壞者，意圖破壞你的代碼庫的穩定性。也許我誇大了一點，但是在做完它之後，你不知道修復一個bug有多麼有趣，並且確信測試會通過，因爲沒有人依賴那些沒有記錄的錯誤行爲來實際發生。 – 2009-12-05 21:35:56

回答

0

你的函數應該理想地只做一件事，不管是什麼「事情」和在什麼粒度級別。

同樣，它們應該在適當的粒度級別上進行描述。如果您打印出一隻ASCII小貓，您可以將其保留爲DisplayKitten()的說明。你不必描述它所做的每件事。

想想吧。如果每一個函數都描述了它所做的每一件事，那麼你的主要功能將不得不描述程序中每一件事都要做的事情，而且這種方法有點矯枉過正。此外，大多數評論將分佈在被調用的函數中，等等，所以該程序最終會以大多可笑的詳細評論結束。

所以，留下一般的函數的功能，只要你的函數名稱足夠描述性（而你的函數名稱）就可以將它們降到最低。如果您或您的用戶需要更多的細節，他們可以檢查代碼。

來源

2009-12-05 19:22:32

+0

謝謝 - 如果我們仔細地評論每一條評論，您的意見對於主要的評論是非常有幫助的。 – pocketdora 2009-12-07 00:17:41

2

您似乎在命名您的功能足夠描述，並讓他們只做一件事（單一責任）。通過閱讀代碼，你基本可以理解他們在做什麼。這將是我的偏好，而不是添加評論。

來源

2009-12-05 19:14:33 klabranche

0

通常我不會提到所有子程序完成的所有工作。它可能變得非常乏味。值得一提的是，如果其中一個子程序執行某些不尋常的事情，或者有其他不明的副作用。

來源

2009-12-05 19:14:52 FrustratedWithFormsDesigner

4

我會說你應該清楚地寫下你的代碼並且適當地命名它，這樣它就可以自我記錄，並且不需要評論讓未來的程序員理解它的功能。然後，您只能使用註釋來記錄API函數（用戶無法訪問代碼庫）或複雜/非顯而易見的事情，而這些事情您無法重構以使其更容易理解。

來源

2009-12-05 19:15:47 tvanfosson

2

我要說的是，在一般情況下，這一段是在正確的軌道上的99％的情況下：

在另一方面，如果 DisplayKitten（）評論明確提到 三個斜槓其次是三個 反斜槓，這似乎與 封裝的精神和 如果DisplayWhiskers（） 稍後更改會變得錯誤。

DisplayKitten（）如何調用DisplayWhiskers（），甚至是它調用它的事實，可能是一個實現細節。

有些情況下，這是不正確的。有時你有一個「便利功能」，其工作就是以特定的方式調用另一個功能。在這種情況下，在文檔中故意破壞封裝可能是有意義的。但是，這些情況是該規則的例外。

來源

2009-12-05 19:17:53

0

保留意見DRY

來源

2009-12-05 19:23:37

4

一般來說，評論應該把注意力集中在代碼做什麼 - 代碼本身記錄了。相反，他們應該專注於爲什麼事情正在完成。

來源

2009-12-05 19:27:42

+2

這個。真的這個。一個簡單的概念，很多開發人員似乎都失去了。 – Chris 2009-12-05 19:40:05

0

「對於這個問題，我並不是要引用代碼中的註釋，而是要將其與函數原型附帶的頭文件中的註釋相提並論。」

如果在整個問題中用單詞「documentation」替換單詞「comments」，您可能會得到不同的答案。我認爲這個增加改變了很多問題。

您承諾的界面和關於您的實現如何完成某些事情的一些注意事項之間存在巨大差異。你應該非常認真地對待前者，並確保它包含呼叫者需要知道的所有內容，而不是更多。後者應儘可能遠離呼叫者，以便將來如果要更改它，則可以在不影響任何其他代碼的情況下執行此操作。

在這種情況下，小貓明顯有鬍鬚，所以應該記錄很多。但小貓的一個重要特徵是它們每邊都有三根鬍鬚嗎？我不知道，這完全取決於真正的問題領域，以及代碼的設計。如果不是，你可能不應該記錄它，也許應該特別提到未來可能會改變晶須的數量而沒有任何警告。

來源

2009-12-05 22:06:05

+0

你說得對，我應該對文檔有所瞭解。感謝您的回答，這很有幫助。 – pocketdora 2009-12-07 00:21:25

0

法點評（最好在Javadoc形式，儘管它猙獰的語法）應伴隨方法，以及應包括調用者需要知道的內容要調用的方法，而不是其他（可能除了什麼subclasser需要知道）。

submethods完成的工作是一個實現細節。事實上，是否存在都是任何子方法都是實現細節。

只是告訴潛在的來電者他們需要知道什麼，例如：displayKitten（）實際上display一隻小貓？如果是這樣，在哪裏？或者它返回一個字符串表示？

您應該給格式？那要看。正如問題中所描述的，小貓的實際表現形式是實施細節嗎？在這種情況下，不，你不應該給格式。但是，如果它符合某個規範，最好引用規範 - 甚至可能在方法名稱中：displayKittenPerFsda246_a()。

來源

2009-12-05 23:24:46 CPerkins

相關問題

 相關問題