SCSS/CSS 文件注释规范

CSS 注释按照等级划分，包括文件级注释、模块级注释、行内级注释3种。注释的目的是让代码阅读者了解到代码本身所不能表达的信息，关键在于“why”，尽量避免“how”，因为如何实现是看代码即可明白的，不需要多此一举（除非实现方式难以看懂），而为什么这么实现就需要注释写明了。 注释的原则是表达清晰，让人一言既明为什么这么做、如何使用。

注释的格式

单行注释，以“/ /”包裹注释内容，注意内容与注释符之间有头尾的空格隔开。例如：

  1. 正确示范：/* 注释内容 */
  2. 错误示范：/*注释内容和注释符头尾要有空格*/

多行注释，以“/*”开头，紧接着换行符。从第二行开始，每一行的开头都是“空格”+“”+“空格”，最后一行以“空格”+“*”+“/”结尾。 如有必要，用“@”+关键词+“空格”注明关键信息。例如：

  1. 正确示范：
  2. /**
  3.  * 注释内容
  4.  * @author xxx
  5.  */
  7. 错误示范：
  8. /*
  9.  注释符第一行应该是“/**”，每一行开头是“* ”
  10.  */
  12. /**
  13.  *每一行注释内容与开头的“*”之间要有空格
  14.  */
  16. /**
  17.  * 注释符结尾只需要“*/”即可
  18.  **/

文件级注释

对于文件而言，最关键的信息在于代码维护者是谁？这份文件是什么时候的版本？文件内容包含什么？ 因此推荐的注释模板如下：

  1. /**
  2.  * ftnlist.css 中转站列表的样式文件，同时也用于写信超大附件的文件列表样式
  3.  * @author molice
  4.  * @date 2014-08-27
  5.  *
  6.  * #reset
  7.  *
  8.  * #layout 主框架布局
  9.  * #list 文件列表
  10.  * #function 公共方法函数
  11.  * #...
  12.  */
  14. /* #reset */
  15. body {
  16.   font-size: 14px;
  17. }
  18. ...

上述推荐模板中，在文件头注释里用“#”列出了当前文件的内容结构，在某个代码段开始处又注明了当前代码段的“#”标志，从而实现类似于文件目录的形式。 为什么使用“#”来标志，一方面是“#”在url内属于hash部分，本身是用来做锚点定位的，其次vim默认配置里，当使用“#”或“*”快捷键搜索当前光标所处的单词时，“#”能和字母一起被识别为一个完整单词，这样整个文件里某个“#”标志只可能出现两次：一次在文件头目录内，一次在实际代码段位置开头。这样就能实现目录搜索定位功能了。

模块级注释

当某个模块有较多分类/拓展的情况，需要一定的说明才能正确使用时，推荐为它加上模块级注释。 模块级注释类似面向对象编程里对某个类进行注释，说明它的作用、使用时有什么依赖、提供哪些方法、class如何嵌套。 以下是一个推荐模板：

  1. /**
  2.  * .qm_list_item
  3.  * + .qm_list_item_BorderNone 不显示item底部的分隔线
  4.  * + .qm_list_item_Accessory 在item右边显示向右箭头
  5.  * + .qm_list_item_Style2 标题、副标题上下排列
  6.  *
  7.  * > [.qm_list_item_control]      可选。在列表左边显示一个控制控件，例如checkbox、radio等
  8.  * > .qm_list_item_content        包裹item内容的容器
  9.  *   > [.qm_list_item_icon]       可选。在内容左边显示一个图片
  10.  *   > .qm_list_item_textWrapper  包裹item文字内容的容器，内部只能摆放文字
  11.  *     > .qm_list_item_title      item的标题，默认为黑色
  12.  *     > .qm_list_item_subtitle   item的副标题，默认会灰色
  13.  *
  14.  */
  15. .qm_list_item {
  16.   ...
  17.   border-bottom:1px solid #000;
  18.   ...
  19. }
  20. .qm_list_item_BorderNone {
  21.   border-bottom:none;
  22. }

其中第一行指明当前模块的名称，一般以根className命名。 从第二行开始，用相邻选择器“+”表示与根className同级的className，一般是一些当前模块的拓展选项。例如模块默认带底部边框线，但又提供一个拓展选项“.qm_list_item_BorderNone”可以在需要时去掉底部边框线。 若要表达“父-子”嵌套的关系，则缩进两个空格，用后代选择器“>”引出子级className。例如上述模板表达了使用模块时html结构应该如何嵌套：

  1. <div class="qm_list_item">
  2.   <div class="qm_list_item_control">这个节点可选，所以注释里用中括号“[]”包起来</div>
  3.   <div class="qm_list_item_content">
  4.     <div class="qm_list_item_textWrapper">
  5.       <div class="qm_list_item_title">这个节点必须放在textWrapper内，所以注释里有缩进和“>”关系</div>
  6.       <div class="qm_list_item_subtitle"></div>
  7.     </div>
  8.   </div>
  9. </div>

行内注释

当某句语句比较特殊，或实现方式与标准的实现方式不同，为了避免阅读时产生疑惑，就必须为语句添加说明。 行内注释紧跟写在需要注释的语句的后面，语句和注释之间不需要有空格。行内注释以“/ ”开始，以“ /”结束。注意开头、结尾均有空格隔开注释内容。

.layout_left {
  float: left;
  margin-right: 10px;
}
.layout_right {
  overflow: hidden; /* 产生BFC，隔开左右两部分内容 */
}