如何在保持StyleCop快樂的同時將常規評論分解爲段落？

有時需要冗長的評論。這可能發生在需要長時間解釋的富有攻擊性的黑客攻擊中。是的，最好完全避免/修復黑客行爲，但通常存在時間壓力，必須將其推向未來。如果是這樣的話，那麼有詳細的評論是非常有幫助的，包括那些會用更好的代碼替換黑客的人。關鍵是要確保他們確切知道黑客正在做什麼以及爲什麼。如何在保持StyleCop快樂的同時將常規評論分解爲段落？

通常需要多個段落。如果允許空白註釋（如//），評論將更具可讀性。然而，StyleCop不喜歡這些，我們總體上贊同它，所以我們試圖堅持所有的建議。現在，我能想到的三個選項：

//// This is a hack ... 
//// .................. 
//// 
//// When fixing this hack make sure ... 
//// ...................................

（我不喜歡第一個，因爲我一般採用雙/三/四註釋註釋掉的代碼段）。

// This is a hack ... 
// .................. 
////         <== This will slide, but I think it looks dumb. 
// When fixing this hack make sure ... 
// ...................................

（我不喜歡第二個選項，我認爲它看起來有點啞）

// <para> 
// This is a hack ... 
// .................. 
// </para> 
// <para> 
// When fixing this hack make sure ... 
// ................................... 
// </para>

（我不愛的第三個選項要麼是非常適合///方法的文檔。，但在這裏它看起來有點亂的地方。

請提出一個更好的辦法。

來源

2010-08-03 Hamish Grubijan

更改Stylecop規則。 – 2010-08-03 15:57:57

StyleCop似乎是一個應該幫助你的工具。但是現在你正在問如何解決這個問題。 – 2010-08-03 16:00:04

爲什麼不直接使用換行符？

// Some comment 
// Some comment 

// Some more comments 
// Some more comments 

// Yet more comments 
// Yet more comments 
int x = 2;

來源

2010-08-03 17:43:34 Jason

不可以。 SA1512：單行註釋後面不能有空行。要在註釋掉一行代碼時忽略此錯誤，請使用'////'而不是'//'開始註釋。 – 2010-08-05 15:57:12

/*
我有一個冗長的評論之作，無論什麼原因，我用的是「slashterix」「塊註釋」風格的任何時間。

總是爲我工作。
YMMV，但這是我最好的建議。 8）
*/

來源

2010-08-06 16:50:17 Task

如何在保持StyleCop快樂的同時將常規評論分解爲段落？

回答

相關問題