PHP我應該寫評論/文檔

Question

一旦我在「清潔代碼」書中讀到不應該寫的評論，因爲他們搞砸了代碼。

然而，「kohana」代碼（作爲衆多代碼之一）在幾乎每一行代碼之前都包含大量文檔和註釋。

我正在創建將在未來由用戶程序員使用的項目......我該如何寫評論呢？

爲了使這更清楚 - 我應該：

每次上課之前

• 寫文檔？
• 在每種方法之前寫文檔？
• 寫@param，@return ...對於每種方法？
• 爲幾乎每一行代碼寫評論，使其更清晰？

Answer 1

您應該：每個類的每個方法

寫@參數之前

寫文檔之前

• 寫文檔，@返回......每個公共方法

對每一行代碼的評論都不是太必要，但我建議他們使用其他方式不清楚或模糊的代碼。

Answer 2

我寫的兩個重大案件的意見/文檔：

• 當一些節目確實不是立即明顯。即使它現在看起來很明顯，也不會在6個月內，或者到另一個試圖維持你的工作的人。
• 當變量/參數/屬性類型不清晰。那時候我添加了一個docblock。

大多數（所有）體面的IDE都具有摺疊甚至隱藏評論的機制。不要放棄它們，因爲一本書告訴了你，或者因爲你認爲它是「雜亂」。

凌亂是一個主觀的術語。我認爲寫一條評論線可以爲未來你節省10個小時的頭痛。

Answer 3

說實話，我會考慮未來的讀者。他們會從評論中受益嗎？就我自己而言，我只對我沒有寫的評論感到遺憾，很少對我所做的不必要的評論感到遺憾。很多時候我都以爲「沒有辦法，我會忘記這個」......並且確實如此。

作爲一種替代方案，您還可以使用完整評論維護代碼的單獨副本，以及刪除大部分/所有評論的發佈版本。

Answer 4

無論你讀過哪本書說的評論都不應該寫出來，你應該馬上扔掉，永遠忘記。我不在乎你是否是唯一一個會使用代碼的人，你仍然應該記錄它。對於我來說，如果您正在處理其他開發人員將使用的代碼，我會嘗試使用PHPDoc（JavaDoc）樣式的文檔，這意味着您將每個類，方法，屬性等文檔記錄爲儘可能徹底。這帶來的一個好處是，許多IDE將實際使用這些信息來完成代碼，使您的應用程序更易於使用。

現在在代碼塊中，我不認爲你需要評論每一行（尤其是那些很容易顯示你在做什麼的行），但是註釋代碼的不同部分，不同的邏輯分支等

另外一個非註釋的事情，我也建議，是使用變量名稱是有意義的（除了簡單的計數器）。通常情況下，人們會變得可愛並且想要使用3-4個字母的變量名稱，因爲一些錯誤的觀點認爲它會在輸入時使用相同的時間，或者縮短它們的代碼。如果你需要一個像product_catalog_iterator這樣的長名來形容一門課，那對我來說比prodcatit或類似的要好。

Answer 5

我是一個不寫評論的人。而是編寫自我評論的代碼。我的意思是你的功能和變量描述他們的工作。例如，你可以把它寫兩種方式：

function foo1($a, $b, $c){ 
return md5($a . $b . $c); 
} 

，或者你可以寫

function encryption($pepper, $content, $salt){ 
return md5($pepper . $content . $salt); 
} 

在這個例子中，你不知道它在做什麼的第一個，但第二次，一個你確切地知道它在做。我唯一需要感覺評論的就是在你編寫非常難看的代碼之後，你需要很長時間才能弄清楚如何去做，而不是很清楚它在做什麼。然而，這應該是遠在兩者之間。

文檔不是一個好主意的原因，是因爲通常發生的事情是，您在函數首次創建時，然後在錯誤修復和維護之後編寫出色的評論。評論從未更新過，現在評論說這個功能沒有做的事情，並提供了困惑，而不是幫助。