Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

关于注释的那点事儿 #4

Open
JasinYip opened this issue Jun 4, 2015 · 0 comments

Comments

@JasinYip
Copy link

commented Jun 4, 2015

前言

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

单行注释和块注释的定义

首先我们来定义一下「单行注释」和「块注释」,在本文中所有说到的单行注释和块注释,都是指语法中所定义的意思,而不是语义上的「一行的注释」和「一大段的注释」。比如在 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
2 participants
You can’t perform that action at this time.