.net註釋應以大寫字母開始並以句點結束？

根據我得到的反饋，我可能會與同事提出這個「標準」。這可能會成爲一個自定義StyleCop規則。有沒有寫過？.net註釋應以大寫字母開始並以句點結束？

因此，Stylecop已經規定此爲summary,param和return文檔標籤。

您認爲從評論中要求相同是否有意義？

在相關說明：如果評論已經很長，那麼它應該被寫爲一個合適的句子？

例如（也許是我太使力來說明一個差評）：

//if exception quit

與

// If an exception occurred, then quit.

如果想通 - 大部分的時間，如果一個困擾寫評論，那麼它可能是信息。考慮這兩個樣本：

//if exception quit 
if (exc != null) 
{ 
    Application.Exit(-1); 
}

和

// If an exception occurred, then quit. 
if (exc != null) 
{ 
    Application.Exit(-1); 
}

可以說，一個不需要評論可言，但由於一個提供，我認爲第二個是更好的。

請備份您的意見。你有評論的藝術的一個很好的參考，特別是如果它涉及。淨？

謝謝。

來源

2010-05-25 Hamish Grubijan

就我個人而言，我會把這些類型的評論放在代碼塊裏面，如果你可以對else條件有一個評論（如果存在的話）。 – 2010-05-25 23:38:21

我經常寫評論，只是爲了幫助我找到代碼段。（我也用的區域這一點。）例如：

// SERVER

因爲IDE colorizes意見，這使得它在方便的時候有這樣簡短的話來堵精神上的東西幫助成段。我通常只做十幾行代碼。如果時間更長，那麼#region似乎更好。

我也經常寫筆記在我的意見，有時像這樣爲自己的參考：

// NOTE: -273.15 is absolute zero in °C, used for a MinValue below

這不是一個漂亮的語法或完整的句子，但它是有道理的。

在哪裏我傾向於使用更加齊全，結構化的句子是我的方法的總結，就像這樣：

/// <summary> 
/// Populates the properties of a Sensor object based on 
/// the XML components of its data file. 
/// </summary>

那些我覺得更容易被別人閱讀和它有助於有冗長和乾淨的格式。

來源

2010-05-25 23:45:43 JYelton

+1對於摘要位，這非常好。我的一些同事設置Resharper去除所有「傳統」評論。 – 2010-05-25 23:53:24

您在代碼中輸入ºs？ – igul222 2010-05-25 23:57:50

當然！這只是alt + 176。我在工作中處理這個符號很多！ :) – JYelton 2010-05-26 00:18:23

花時間寫出清晰，可讀，可理解的評論永遠不會浪費。我有多少次在稍後的日子重新閱讀我自己的評論，以致於很難理解它們。潦草寫作或嚴格格式化評論的人通常會在其代碼中使用相同的特徵。

來源

2010-05-25 23:37:18 Ricibob

如果代碼需要註釋，那麼它應該很好地形成，因爲IMO可能需要解釋一個（非平凡的）概念。

應避免在您的示例中出現瑣碎的註釋。他們除了噪音之外什麼都不加

來源

2010-05-25 23:39:10 spender

對於避免無關緊要的評論的提示+1 – 2010-05-26 11:09:43

如果你在Visual Studio中評論方法，你應該考慮在方法的頂部使用summary和params。這樣你就可以在代碼完成時獲得有關該方法的詳細信息下面是一個例子

/// <summary> 
    /// you summary here 
    /// </summary> 
    /// <param name="param1">Describe parameter usage</param> 
    /// <param name="param2">Describe parameter usage</param>

來源

2010-05-25 23:48:33

引用OP「所以，Stylecop已經規定了這個摘要，參數和返回文檔標籤」... – spender 2010-05-25 23:52:29

我發現，當我儘量簡短帶註釋（即不完整的句子，片段），我經常離開了關鍵假設或詞實際上澄清意義。我現在很難提出一個具體的例子，對不起。

儘管如此，強迫自己編寫完整，適當的句子也迫使你更多地思考你真正想要評論的內容。我經常發現自己重新思考我真正想要寫入評論的內容。

在簡潔的祭壇上犧牲清晰度沒有任何理由。有人需要了解將來的代碼。評論是針對他們的，所以讓他們很容易理解。

來源

2010-05-26 08:31:38

.net註釋應以大寫字母開始並以句點結束？

回答

相關問題