• 注释
    • 1. 普通注释,注释文字左右各留一个空格。
    • 2. 区块注释
    • 3. Doxygen 风格的注释
    • 4. CSS 预处理工具中的单行注释
    • 5. clean-css 等压缩工具中的注释

    注释

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

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

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