Jasin Yip

关于注释的那点事儿

前言

虽然有些人会认为,最好的代码不需要注释。但是我认为这样的观点太过于偏激,规范的注释可以帮助我们理解别人或者自己以前写的代码。撰写这篇文章的原因,是我所在的公司(计蒜客)的项目里面的注释,很不规范,所以希望通过制定这样的一个规范来改善这个问题。最初发表于计蒜客的技术分享博客

单行注释和块注释的定义

首先我们来定义一下「单行注释」和「块注释」,在本文中所有说到的单行注释和块注释,都是指语法中所定义的意思,而不是语义上的「一行的注释」和「一大段的注释」。比如在 CoffeeScript 中的 # 就是单行注释,### 就是块注释。

什么时候使用单行注释?

我们建议 总是 (Always) 使用单行注释,因为这样我们可以非常方便地去对一整块代码进行注释,举个例子:

假设我们有这么一段 CSS 代码

.foo { color: #123; } /* 注释 1 */
.bar { color: #321; } /* 注释 2 */

如果我们想对这一段代码进行注释,我们可能会这样写:

/*
.foo { color: #123; } /* 注释 1 */
.bar { color: #321; } /* 注释 2 */
*/

然而,你会发现,当第 1 个/* 检测到第 1 个 */ 时,它就会以为这里就是结束的地方,所以最后面的那个 */ 并没有被匹配起来,这样就会造成语法出错。

所以我们建议我们在开发当中,总是 (Always) 使用单行注释,而不是块注释。

什么时候使用块注释

只有 3 种情况可以使用块注释:

  1. 当我们需要把一大段代码注释掉的时候;
  2. 当自动化文档生成工具的语法要求使用块注释的时候;
  3. 该编程语言只有块注释语法的时候,比如 HTML。

在其它任何情况下,都 永远不要 (Never) 使用块注释。

多行注释

如果我们的注释是需要跨行的,我们仍然需要使用单行注释,比如:

# 这是第一段注释,这是第一段注释
# 这是第一段注释,这是第一段注释,这是第一段注释
#
# 这是第二段注释,这是第二段注释
# 这是第二段注释,这是第二段注释,这是第二段注释

一些规范的注释使用示例

对类或函数的注释

我们应该将注释写在类或函数中的第一行,并缩进一层,同时留空一行,例:

foo = ->
    # 这是函数的描述

    # 在这里开始写代码

备注:目前我们暂时没有使用自动化文档生成工具,所以没有太多的对于参数的要求,当以后引入自动化文档生成工具后,再会对参数的要求进行修改。

对 HTML、CSS/Less 闭合处的注释

我们留意到,当代码的嵌套层级比较多,并且一个屏幕不能把完整一段代码完整地显示的时候,我们将会看到闭合处看到一大堆的闭合标签或者闭合符 },这不利于以后的维护,所以我们推荐在闭合处进行注释。

格式要求:在闭合处后面空一格、注释符与注释内容之间也空一格,用 / 表示闭合标签,并且根据 CSS 选择器 的语法来描述,示例:

HTML
<div class="foo">
    <div>
        <div class="bar">
            <div></div>
        </div> <!-- /.bar -->
    </div>
</div> <!-- /.foo -->
CSS/Less
.foo {
    .bar {
        .foo2 {
            .bar2 {}
        }
    } // /.bar
} // /.foo

标签:jasinyip

仅有 1 条评论

  1. GL GL

    我的想法反而相反——为了防止因为不同的程序对 line-ending sequence 的定义不同,我总是使用块注释而不是行注释。

    下次要不要写写关于如何写技术文档的规范呀。

添加新评论