如何将常规评论分成段落，同时让 StyleCop 满意？
有时需要冗长的评论。当存在需要长时间解释的丑陋黑客时，可能会发生这种情况。是的，最好完全避免/修复黑客攻击，但通常存在时间压力，必须将其推迟到未来。如果是这样的话，那么详细的评论是非常有帮助的，包括那些想要用更好的代码替换 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>
（我也不喜欢第三个选项。它非常适合 /// 方法文档，但这里看起来有点不合适，
请提出更好的方法。
Sometimes there is a need for lengthy comments. This can happen when there is a fugly hack which needs long explanation. Yes, it is better to avoid/fix the hack altogether, but often there is time pressure and one has to push it off into the future. If that is the case, then having a detailed comment is quite helpful, including those who would be replacing a hack with better code. The key would be making sure that they understand exactly what the hack is doing and why.
Often that requires multiple paragraphs. The comment would be more readable if blank comments such as // were allowed. However, StyleCop does not like those, and we agree with it overall, so we try to stick with all of its suggestions. Now, i can think of three options:
//// This is a hack ...
//// ..................
////
//// When fixing this hack make sure ...
//// ...................................
(I do not like the first one because I generally use double/triple/quadruple comments for commenting out sections of code).
// This is a hack ...
// ..................
//// <== This will slide, but I think it looks dumb.
// When fixing this hack make sure ...
// ...................................
(I do not like the second option; I think it looks sort of dumb)
// <para>
// This is a hack ...
// ..................
// </para>
// <para>
// When fixing this hack make sure ...
// ...................................
// </para>
(I do not love the third option either. It is well-suited for /// method documentation, but here it looks sort of out-of-place.
Please suggest a better way.
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（2）
/*
每当我要发表冗长的评论时，无论原因如何，我都会使用“slashterix”“块评论”风格。
总是对我有用。
YMMV，但这是我最好的建议。 8）
*/
/*
Any time I've got a lengthy comment to make, regardless of cause, I use the "slashterix" 'block comment' style.
Always works for me.
YMMV, but it's my best suggestion. 8 )
*/
为什么不直接使用换行符呢？
Why not just use linebreaks?