注释

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

注释风格应当相对简洁,做如下规范:

  • 区块注释放在单独一行。
  • 保持注释内代码的缩进。
  • 为了注释文字更具有可读性,合理控制每行的字数,推荐每行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. */