注释

良好的注释使代码更具有可读性和可维护性，尤其是多人协作的项目，不要让团队其他成员来猜测一段
代码的意图。

注释风格应当相对简洁，做如下规范：

  • 区块注释放在单独一行。
  • 保持注释内代码的缩进。
  • 为了注释文字更具有可读性，合理控制每行的字数，推荐每行80个字符（40个汉字）以内。

提示：通过扩展 emmet 等工具（例如emmet-plus）可以快速输出统一的注释风格。

CSS 文件中有如下几种注释：

1. 普通注释，注释文字左右各留一个空格。

  1. /* 普通注释 */

2. 区块注释

注释横线的长度为80个字符，作为换行参考。

一级区块注释 

  1. /* ==========================================================================
  2.    一级区块注释
  3.    ========================================================================== */

二级区块注释 

  1. /* --------------------------------------------------------------------------
  2.    二级区块注释
  3.    -------------------------------------------------------------------------- */

3. Doxygen 风格的注释

每个 CSS 文件的头部或区块的开始处应当包含 Doxygen 风格的注释，以阐明该文件或这段代码的
作用、作者、最后更新时间等信息。

Doxygen 风格的注释以 /* 开始，每行以 号开头。

  1. /**
  2.  * Doxygen 风格的注释示例
  3.  * @file：    文件信息
  4.  * @author:   一丝
  5.  * @update:   2013-11-5
  6.  * @note:     注解
  7.  * @doc:      相关文档
  8.  *
  9.  * 这里是更详细的描述，当然我们要把字数控制在每行80个字符（40个汉字）以内。如果
  10.  * 一行写不下，需要另起一行。
  11.  */

Doxygen 风格的注释内如果包含其他代码，不写开头的 * 号，以方便复制代码。

  1.  /**
  2.  * Doxygen 风格的注释包含代码
  3.  * 
  4.  * 例如我们可以在注释中嵌入 HTML 代码，同样保持代码的缩进。
  5.  *
  6.   <div class="mod">
  7.     <p>这个模块名叫 mod</p>
  8.   </div>
  9.  */

4. CSS 预处理工具中的单行注释

Sass， LESS， Stylus 中可以使用单行注释。

  1. // 注释内容

5. clean-css 等压缩工具中的注释

clean-css 是一个 CSS 压缩工具，为了保留 CSS 文件的版权信息等特殊需求，支持以下形式的注释

  1. /*!
  2.   这里是版权信息或者重要的注释，压缩后不会被删除
  3. */