注释规范

注释规范的重要性

良好的注释规范能提升代码可读性，便于团队协作和维护。CSS作为样式表语言，合理的注释能清晰表达样式模块划分、功能说明以及特殊处理原因。

单行注释规范

单行注释适用于简短说明，使用//作为前缀，注释内容与符号之间保留一个空格：

// 主标题样式 
h1 {
  font-size: 2rem;
}

// 导航栏背景色
.navbar {
  background-color: #f8f9fa;
}

注意事项：

1. 注释应写在被描述对象上方
2. 注释行与被注释代码间不留空行
3. 每行注释不超过80个字符

多行注释规范

复杂模块建议使用多行注释，采用/* */格式：

/*
 * 卡片组件样式
 * 包含卡片容器、标题和内容三部分
 * 使用BEM命名规范
 */
.card {
  border-radius: 8px;
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

多行注释要点：

1. 首行和末行只包含注释符号
2. 中间每行以*开头并缩进一个空格
3. 注释块上下各保留一个空行

模块划分注释

大型样式文件应使用特殊注释标记模块边界：

/* ======================
   布局样式
   ====================== */

/* ======================
   表单组件
   ====================== */

推荐使用等号或连字符构成视觉分隔线：

• 至少10个等号或连字符
• 模块名称居中显示
• 上下各保留两个空行

条件注释

针对特定浏览器或环境的样式应添加说明：

/* IE9以下版本圆角兼容方案 */
.rounded {
  border-radius: 5px;
  behavior: url(border-radius.htc); /* 使用HTC行为文件 */
}

颜色值注释

对于特殊颜色值应说明用途：

.color-palette {
  --primary: #3498db;  /* 主品牌色 */
  --danger: #e74c3c;   /* 错误提示色 */
  --success: #2ecc71;  /* 成功状态色 */
}

禁用代码注释

临时禁用的代码应保留并添加说明：

/*
.dropdown-menu {
  display: none;  // 二期功能暂缓
}
*/

文档头注释

文件头部应包含基础信息：

/*!
 * 项目名称：电商平台样式表
 * 创建日期：2023-06-15
 * 最后修改：2023-08-20
 * 作者：前端团队
 * 描述：包含全局样式和组件库
 */

特殊标记注释

使用约定俗成的标记提高可读性：

// TODO: 需要优化移动端适配
.responsive-img {
  max-width: 100%;
}

// FIXME: Safari浏览器下存在渲染问题
.animation-box {
  transform: rotate(15deg);
}

常见标记说明：

• TODO：待完成事项
• FIXME：需要修复的问题
• HACK：临时解决方案
• NOTE：重要说明事项

预处理语言注释

Sass/Less等预处理器的注释规范：

// 单行注释不会编译到CSS
/* 多行注释会保留在输出中 */

/// 文档注释（SassDoc）
/// @group utilities
/// @param {Number} $size - 尺寸值
@mixin size($size) {
  width: $size;
  height: $size;
}

注释与版本控制

结合Git的注释建议：

/* [v1.2.3] 新增浮动按钮样式 */
.float-btn {
  position: fixed;
  right: 20px;
  bottom: 20px;
}

注释密度控制

合理控制注释密度：

1. 每10-15行代码应有1-2行注释
2. 自解释的代码不必过度注释
3. 复杂算法或特殊逻辑必须注释

注释风格一致性

团队应统一：

1. 中文或英文注释（推荐英文）
2. 标点符号使用规范
3. 专业术语统一
4. 注释层级划分标准

注释维护责任

注释更新要求：

1. 修改代码时同步更新相关注释
2. 删除代码时移除对应注释
3. 过时的TODO标记应及时清理
4. 定期进行注释审查

注释工具集成

利用工具增强注释：

1. 配置ESLint的注释规则检查
2. 使用Stylelint验证注释格式
3. 集成SassDoc生成样式文档
4. 通过Prettier统一注释格式

# Stylelint注释规则示例
"comment-word-blacklist": [
  ["/^TODO:/", "FIXME"],
  {
    "message": "请使用英文注释（TODO/FIXME）"
  }
]