Иногда возникает необходимость в длинных комментариях. Это может произойти, когда есть грубый взлом, который требует длинных объяснений. Да, лучше вообще избегать / исправлять взлом, но часто возникает нехватка времени, и нужно отодвинуть его в будущее. Если это так, то подробный комментарий весьма полезен, в том числе и тем, кто заменит взлом на лучший код. Ключом было бы убедиться, что они точно понимают, что делает хакер и почему.
Часто для этого требуется несколько абзацев. Комментарий был бы более читабельным, если бы были разрешены пустые комментарии, такие как //. Однако 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>
(Мне также не нравится третий вариант. Он хорошо подходит для документации /// метода, но здесь он выглядит неуместно.
Пожалуйста, предложите лучший способ.