評論風格畫廊...發表你的評論風格

我喜歡瀏覽其他人的代碼，看看他們如何評論他們的風格，大多數人使用*和////的混合，當然這一切取決於語言，但我肯定看到了一些好的方法來評論和一些不好的方法。一個編碼頁面可以真正地與正確的評論結構一起使用，並且使得在沒有任何知識的情況下進入項目的人很容易閱讀。評論風格畫廊...發表你的評論風格

我很好奇看到人們認爲什麼是最好的方式來設置評論，部門分區等。這可能是HTML，PHP或其他任何事情。

來源

2011-08-04 pfunc

PHP：
我個人使用//爲方法/函數內的一切。這是令人討厭的，如果有人使用/* */，因爲它使得更難註釋代碼塊

爲了便於記錄，我使用了與javadoc非常相似的phpdoc使用。

/** 
* Overall description 
* @keyword - description 
*/

通常是一個很好的規則是，如果你去15-20行沒有任何意見，你需要把一些意見，除非代碼是真正的自我解釋。雖然當時你可能會認爲你會記得你的500線功能和它所做的一切，但你經常不會。如果是別人試圖進入並理解你的代碼，那對他們來說只會更困難！

來源

2011-08-04 13:27:07 afuzzyllama

同樣在這裏 - 這兩個塊的評論是必要的，和文件處理 - jsdoc在我的情況。 – danjah

A面節點（快速鏈接，不是我的）：http://www.heartysoft.com/ninja-coding-code-comments

爲什麼我不喜歡評論

我試圖避免評論我的代碼的主要原因是概念自解釋代碼的。代碼應該是自我解釋 - 任何人閱讀代碼應該明白髮生了什麼（當然，給定一些域名的知識）。依靠評論來解釋發生了什麼幾乎不是一個好主意。代碼將比評論更新更頻繁。無論你的團隊多麼警惕，這是必然會發生。充其量，這可能會導致評論稍微過時。在最壞的情況下，陳舊的評論可能完全誤導代碼實際上在做什麼。

我總是試圖重構我的代碼，以便它不需要任何附加說明。

所以我最終得到的結果只有通常的xDoc註釋來自動生成APIDoc。即使這些評論可以在很大程度上自動生成。

在特殊情況下（例如操作系統特定問題），我嘗試找到討論問題並添加鏈接的公共網站。如果鏈接在未來的時間中斷 - 狗屎發生。

AS3：

/** 
* This is a usual doc comment for a type or property. 
*/ 

/* 
* This is a marker of a particular longer section of code. 
*/ 

// This is a single line comment before a or at end of a line of code.

來源

2011-08-04 13:30:03

儘管我傾向於在更高層次上（抽象類和類似）達成一致，但在較低層次上，我肯定會寫評論來解釋我期望的事情會經常發生變化。我不認爲我的代碼像我認爲的那樣「完全可讀」，並且我還假定一些承包商的代碼是gunna搖滾起來並且像.. wtf ?!所以快速修復或古怪的代碼，我會def。評論它。 – danjah

「總是假設將來負責維護你的代碼的人是一個知道你住在哪裏的精神病患者......」 – Landric

@Jens：代碼應該是不言自明的，但是如果你處理的是一個非常大的一段代碼？ – 2011-08-04 14:20:17

在AS3中，我用這個：

/** 
* 
* to comment (if necessary) a method or a group of related methods 
* 
*/

，而我用這個：

//

爲單行註釋。

此外，我通常會插入空的//註釋以獲得更多的代碼readeability。

來源

2011-08-04 14:15:06

評論風格畫廊...發表你的評論風格

回答

相關問題