编写如一、符合习惯的CSS的原则-注释 - 书目录

编写如一、符合习惯的CSS的原则-注释

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

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

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

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

CSS示例:

/* ==========================================================================
   区块代码注释
   ========================================================================== */

/* 次级区块代码注释
   ========================================================================== */

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

/* 一般的注释 */