Comment découper des commentaires réguliers en paragraphes tout en gardant StyleCop heureux?

Question

Parfois, il y a un besoin de longs commentaires. Cela peut arriver quand il y a un hack fugly qui a besoin d'une longue explication. Oui, il est préférable d'éviter/de réparer complètement le piratage, mais il y a souvent une contrainte de temps et il faut le repousser dans le futur. Si tel est le cas, alors avoir un commentaire détaillé est très utile, y compris ceux qui remplaceraient un hack avec un meilleur code. La clé serait de s'assurer qu'ils comprennent exactement ce que fait le hack et pourquoi.

Souvent, cela nécessite plusieurs paragraphes. Le commentaire serait plus lisible si des commentaires vierges tels que // étaient autorisés. Cependant, StyleCop n'aime pas ceux-ci, et nous sommes globalement d'accord, alors nous essayons de coller avec toutes ses suggestions. Maintenant, je peux penser à trois options:

//// This is a hack ... 
//// .................. 
//// 
//// When fixing this hack make sure ... 
//// ................................... 

(je n'aime pas le premier parce que je l'utilise généralement double/triple/quadruple commentaires pour commenter les sections de code).

// This is a hack ... 
// .................. 
////         <== This will slide, but I think it looks dumb. 
// When fixing this hack make sure ... 
// ................................... 

(je n'aime pas la deuxième option, je pense qu'il semble sorte de bête)

// <para> 
// This is a hack ... 
// .................. 
// </para> 
// <para> 
// When fixing this hack make sure ... 
// ................................... 
// </para> 

(je n'aime pas la troisième option soit Il est bien adapté pour /// documentation de la méthode. , mais ici il semble en quelque sorte hors place.

S'il vous plaît suggérer une meilleure façon.

Answer 1

Pourquoi ne pas utiliser linebreaks?

// Some comment 
// Some comment 

// Some more comments 
// Some more comments 

// Yet more comments 
// Yet more comments 
int x = 2; 

Answer 2

/*
Chaque fois que j'ai un long commentaire à faire, quelle que soit la cause, je l'utilise « slashterix » style "de bloc de commentaire.

Fonctionne toujours pour moi.
YMMV, mais c'est ma meilleure suggestion. 8)
*/