C/C++:我应该怎么样写注释?

作为一个程序员来讲,痛苦的事情罕有过于维护一堆没有注释的代码了。最近才听说有的人发明了一个新词汇:三无程序员,所谓“无缩进、无注释、无文档”。注释也列于其中,可见还是有说一说的必要的。

规则 1:注释不要太少,却也不要多到侮辱其他程序员的智慧。
太少了不利于代码的浏览者掌握整体结构,需要不断猜测原作者的用意,太多了则容易干扰视线,导致看很少的一段代码也要把滚动条拖来拖去。

规则 2:注解单行代码的注释尽量写在本行代码的后面。如:

如果需要换行,则写成如下形式或者参照规则 3:

规则 3:注释多行代码或者注释本身需要多行,将注释写在代码的前面,并且与代码保持相同的缩进。如:

如果更喜欢 C 语言的注释风格,则是这样:

还请注意将注释相关的代码与以下的其他代码用至少一个空行分开。

规则 4:如果使用 C++ 风格的注释符号,请在 // 与注释文字之间留一个空格。
没有别的意义,只是为了美观。

小技巧:在注释大段代码(尤其是超过一屏)时,推荐使用如下注释方法:

一旦要把注释掉的代码放开,则只需要在注释开始符号前增加一个 / 即可,不必再寻找并处理注释的结束符号。

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注