coding-style - 你如何设计主要和次要评论？

Question

有时我想写一个“主要”注释来描述一大块代码，然后写一个“次要”注释来描述该代码块中的几行:

// Major comment

// Minor comment
...

// Minor comment 2
...

主要注释看起来很奇怪，没有直接在其下方的代码，并且您无法直观地看出它在下面描述了多少代码。

你如何看待这些评论？

(我记得不久前在 Code Complete 中读到过这个，但我不拥有这本书。)

Answer 1

我对“主要”评论使用多行评论:

/*
 * yada yada yada
 */

并为次要的使用单行注释。

我知道有些人不喜欢使用/* */样式的注释，因为它使自动注释和取消注释 block 变得更加困难......但我喜欢它们的外观，并且我坚信代码应该在美学上令人愉悦读。

这也意味着您应该能够在很大程度上解析代码的结构而无需阅读细节，这意味着我倾向于使用相当多的空格和分隔注释行来帮助分解。因此，对于我想评论的 block ，我可能会写:

/**
 * detailed description ...
 */

code

// -- minor comment
code

code
// --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---