关于注释的那点事儿

[JasinYip]

前言

昨天跟昊然讨论了一下关于注释的问题，因为我们目前注释比较混乱，所以现在希望通过制定规范来改善这一状况。

单行注释和块注释的定义

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

什么时候使用单行注释？

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

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

.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