前言
虽然有些人会认为，最好的代码不需要注释。但是我认为这样的观点太过于偏激，规范的注释可以帮助我们理解别人或者自己以前写的代码。撰写这篇文章的原因，是我所在的公司（计蒜客）的项目里面的注释，很不规范，所以希望通过制定这样的一个规范来改善这个问题。最初发表于计蒜客的技术分享博客。
单行注释和块注释的定义
首先我们来定义一下「单行注释」和「块注释」，在本文中所有说到的单行注释和块注释，都是指语法中所定义的意思，而不是语义上的「一行的注释」和「一大段的注释」。比如在 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
|