Sass注释

1. 简介

本节内容我们将讲解 Sass 中的单行注释和多行注释，以及 Sass 注释的书写规范，良好的注释习惯可以让我们的代码更容易维护，让接手我们代码的合作者更高效。

2. 什么是 Sass 注释

注释就是说你可以在代码中以特定的方式为代码增加注解，每种编程语言都拥有自己的注释方式，在 Sass 中也不例外，注释可以让我们为重要的代码增加注解以方便我们和其他开发者查阅。

3. Sass注释的使用

在 Sass 中的任何地方你都可以编写一段注释，Sass 支持标准的 CSS 单行注释（//）和多行注释（/* */），我们接下来就看看它们的使用。

3.1 单行注释

单行注释是在 // 后面跟你的注释内容，直到行尾，要记住 Sass 中的单行注释不会被编译到 CSS 中，也就是说在转换为 CSS 代码后，是不会包含你写的单行注释的！我们举个例子来看下：

// This is a comments
// This is a comments
.box2 {
  width: 200px;
  height: 100px;
  p {
    color: red
  }
  .main {
    width: 100%;
  }
}

上面的代码转换为 CSS 如下：

.box2 {
  width: 200px;
  height: 100px;
}
.box2 p {
  color: red;
}
.box2 .main {
  width: 100%;
}

从上面的代码中我们可以看出，转换为 CSS 后我们在 Sass 中写的单行注释消失了。

3.2 多行注释

多行注释是在 /* */ 的两个星号中间来编写注释内容，以 /* 开头，换行的话每一行都以 * 号开头，最终以 */ 结尾，多行注释是会被编译到 CSS 中的，并且在多行注释中我们可以使用插值，如果你忘记了什么是插值，赶快复习一下前面的 Sass 插值章节。下面我们举例看下多行注释：

/* This is a comment
 * contain interpolation:
 * 1 + 1 = #{1 + 1}
 * 8 * 8 = #{8 * 8}
 */
.box2 {
  width: 200px;
  height: 100px;
  p {
    color: red
  }
  .main {
    width: 100%;
    heigth: auto
  }
}

上面的代码转换为 CSS 如下：

/* This is a comment
 * contain interpolation:
 * 1 + 1 = 2
 * 8 * 8 = 64
 */
.box2 {
  width: 200px;
  height: 100px;
}
.box2 p {
  color: red;
}
.box2 .main {
  width: 100%;
  heigth: auto;
}

通过上面的代码可以看出，多行注释最终将会被编译为 CSS 的多行注释并带到 CSS 中去，而且在多行注释中可以使用插值来进行一些运算。

在默认的情况下，如果处于压缩模式，则转换后的 CSS 中也是不包含多行注释的，如果你忘了什么是压缩模式，赶快复习下 Sass 输出格式章节。所以我们可以通过以 /*! 开头，来保证多行注释在任何模式下都会被转换为 CSS 输出。我们举例看下：

/*! This comment will be 
* included even in every mode. */
.box2 {
  width: 200px;
  height: 100px;
  p {
    color: red
  }
  .main {
    width: 100%;
    heigth: auto
  }
}

通过上面这种注释方式就可以保证你的注释内容在任何模式下都会被输出。

4. 注释书写规范

在 Sass 中书写注释首先要记住，要根据情况来选择你使用上面哪种注释方式，其余的一些注释规范不同的团队可能有不同的标准，遵循你的团队的代码规范即可。如果没有的话你可以遵照 CSS 的注释规范，同时我们的项目中不允许使用 /*! */ 的方式注释，因为我们要确保压缩版的 CSS 中是不包含任何注释的！

我这里写出一些我们的注释书写规范：

• 注释不允许嵌套
• 两条注释间使用换行分隔
• 函数必须编写注释来写明函数的作用、入参和出参
• mixin 必须编写注释写明作用
• 公共变量必须编写注释写明作用
• 公共样式必须编写注释写明作用
• 用于继承的文件必须编写注释写明使用场景
• 如有某些代码需要在后期修改或优化，需要编写注释，其注释中的内容需要以 TODO 开头有

除了上面这些规范我们还要求在每个文件的头部注释当前文件的创建时间、作者和对于当前文件内容的描述，就如同下面这样：

/*
* Auth: ElvisYang
* Date: Mar 22 2018
* Desc: This is common scss
*/
.edit-price {
  .label {
    width: 125px;
    text-align: right;
  }
}

上面这种方式可以让别人打开文件就清楚的看见文件的一个描述和作者，所以这个也纳入了我们的注释规范中，这种注释你可以通过设置你的 IDE 来自动生成。

5. 实战经验

在实际的项目中注释是必不可少的，在任何语言中都一样。 Sass 作为一门 CSS 扩展语言，在实际项目中会定义很多函数、mixin 和变量等，所以你必须为它们编写合理的注释，这样方便你自己或者其他人后期的维护，而且压缩格式我们一般都是输出不带注释的 CSS 代码的。

除此之外需要注意遵循团队的注释规范，一般规范都由团队的 leader 或架构师来制定，如果你的项目中没有制定这些规范，请遵循 CSS 的注释规范或者业界通用的规范，当然你也可以选择我前面列出来的规范。总之要记住，注释和代码一样重要！

6. 小结

本节我们讲解了 Sass 中注释的使用方式和注释的书写规范，在 Sass 中有单行注释和多行注释，单行注释不会输出到 CSS 代码中，多行注释可以输出到 CSS 代码中，此外在多行注释中还可以使用插值。编写一手简单、易懂的注释是一个优秀程序员的基本素养，会为你的代码加分，在你的 Sass 代码中灵活的应用注释吧！