如何在保持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快乐的同时将常规评论分解为段落？

回答

相关问题