c# - 如何在让 StyleCop 开心的同时将常规评论分成段落？

Question

有时需要冗长的注释。当有一个需要很长时间解释的错误 hack 时，就会发生这种情况。是的，最好完全避免/修复黑客攻击，但通常会有时间压力，并且必须将其推迟到 future 。如果是这种情况，那么详细的评论将非常有帮助，包括那些将用更好的代码替换 hack 的人。关键是要确保他们准确理解黑客在做什么以及为什么这样做。

通常这需要多个段落。如果允许诸如 // 之类的空白注释，注释将更具可读性。然而，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>

(我也不喜欢第三个选项。它非常适合 /// 方法文档，但在这里看起来有点不合适。

请提出更好的方法。

Answer 1

/*
每当我要发表冗长的评论时，无论出于何种原因，我都会使用“slashterix”“ block 评论”风格。

总是为我工作。
YMMV，但这是我最好的建议。 8)
*/