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.