3. 注释

良好的注释是非常重要的。请留出时间来描述组件(component)的工作方式、局限性和构建它们的方法。不要让你的团队其它成员
来猜测一段不通用或不明显的代码的目的。

注释的风格应当简洁,并在代码库中保持统一。

  • 将注释放在主题上方并独占一行。
  • 控制每行长度在合理的范围内,比如80个字符。
  • 使用注释从字面上将CSS代码分隔为独立的部分。
  • 注释的大小写应当与普通句子相同,并且使用一致的文本缩进。

提示:通过配置编辑器,可以提供快捷键来输出一致认可的注释模式。

CSS示例:

  1. /* ==========================================================================
  2. 区块代码注释
  3. ========================================================================== */
  4. /* 次级区块代码注释
  5. ========================================================================== */
  6. /**
  7. * “Doxygen式注释格式”的简短介绍
  8. *
  9. * 较长的说明文本从这里开始,这是这段文字的第一句话,而且这句话还
  10. * 没结束,过了好一会儿,我了个去终于结束了,烦不烦啊。
  11. *
  12. * 当需要进行更细致的解释说明、提供文档文本时,较长的说明文本就很
  13. * 有用了。这种长长的说明文本,可以包括示例HTML啦、链接啦等等其
  14. * 他你认为重要或者有用的东西。
  15. *
  16. * @tag 这是一个叫做“tag”的标签。
  17. *
  18. * TODO: 这个“‘需做’陈述”描述了一个接下来要去做的小工作。这种文本,
  19. * 如果超长了的话,应该在80个半角字符(如英文)或40个全角字符(
  20. * 如中文)后便换行,并(在“ * ”的基础上)再在后面缩进两个空格。
  21. */
  22. /* 一般的注释 */