前言
虽然有些人会认为,最好的代码不需要注释。但是我认为这样的观点太过于偏激,规范的注释可以帮助我们理解别人或者自己以前写的代码。撰写这篇文章的原因,是我所在的公司(计蒜客)的项目里面的注释,很不规范,所以希望通过制定这样的一个规范来改善这个问题。最初发表于计蒜客的技术分享博客。
单行注释和块注释的定义
首先我们来定义一下「单行注释」和「块注释」,在本文中所有说到的单行注释和块注释,都是指语法中所定义的意思,而不是语义上的「一行的注释」和「一大段的注释」。比如在 CoffeeScript 中的 #
就是单行注释,###
就是块注释。
什么时候使用单行注释?
我们建议 总是 (Always) 使用单行注释,因为这样我们可以非常方便地去对一整块代码进行注释,举个例子:
假设我们有这么一段 CSS 代码
1
2
|
.foo {
color
:
#123
; }
/* 注释 1 */
.bar {
color
:
#321
; }
/* 注释 2 */
|
如果我们想对这一段代码进行注释,我们可能会这样写:
1
2
3
4
|
/*
.foo { color: #123; } /* 注释 1 */
.bar {
color
:
#321
; }
/* 注释 2 */
*/
|
然而,你会发现,当第 1 个/*
检测到第 1 个 */
时,它就会以为这里就是结束的地方,所以最后面的那个 */
并没有被匹配起来,这样就会造成语法出错。
所以我们建议我们在开发当中,总是 (Always) 使用单行注释,而不是块注释。
什么时候使用块注释
只有 3 种情况可以使用块注释:
- 当我们需要把一大段代码注释掉的时候;
- 当自动化文档生成工具的语法要求使用块注释的时候;
- 该编程语言只有块注释语法的时候,比如 HTML。
在其它任何情况下,都 永远不要 (Never) 使用块注释。
多行注释
如果我们的注释是需要跨行的,我们仍然需要使用单行注释,比如:
# 这是第一段注释,这是第一段注释 # 这是第一段注释,这是第一段注释,这是第一段注释 # # 这是第二段注释,这是第二段注释 # 这是第二段注释,这是第二段注释,这是第二段注释
一些规范的注释使用示例
对类或函数的注释
我们应该将注释写在类或函数中的第一行,并缩进一层,同时留空一行,例:
foo = -> # 这是函数的描述 # 在这里开始写代码
备注:目前我们暂时没有使用自动化文档生成工具,所以没有太多的对于参数的要求,当以后引入自动化文档生成工具后,再会对参数的要求进行修改。
对 HTML、CSS/Less 闭合处的注释
我们留意到,当代码的嵌套层级比较多,并且一个屏幕不能把完整一段代码完整地显示的时候,我们将会看到闭合处看到一大堆的闭合标签或者闭合符 }
,这不利于以后的维护,所以我们推荐在闭合处进行注释。
格式要求:在闭合处后面空一格、注释符与注释内容之间也空一格,用 /
表示闭合标签,并且根据 CSS 选择器 的语法来描述,示例:
HTML
1
2
3
4
5
6
7
|
<
div
class
=
"foo"
>
<
div
>
<
div
class
=
"bar"
>
<
div
></
div
>
</
div
>
<!-- /.bar -->
</
div
>
</
div
>
<!-- /.foo -->
|
CSS/Less
1
2
3
4
5
6
7
|
.foo {
.bar {
.foo
2
{
.bar
2
{}
}
} // /.bar
} // /.foo
|