注释格式为/* 注释 */

在CSS/SCSS开发中，良好的注释习惯是维护代码可读性和团队协作的关键。本文将详细介绍/* 注释 */格式的规范使用，通过正反示例对比，帮助开发者掌握CSS注释的最佳实践。

基本注释格式规范

CSS/SCSS的标准注释格式是多行注释/* 注释 */，这与JavaScript等语言不同（不支持//单行注释）。

css 复制代码

/* 主页面标题样式 */
.page-title {
  font-size: 2rem;
  color: #333;
}

css 复制代码

// 主页面标题样式 (CSS不支持这种注释)
.page-title {
  font-size: 2rem;
  color: #333;
}

正确示例：

css 复制代码

/* 
 * 样式表：主页面布局
 * 作者：张三
 * 创建日期：2023-05-20
 * 最后修改：2023-06-15
 */

错误示例：

css 复制代码

/* 主页面样式 作者张三 */
/* 缺少完整信息，格式不统一 */

正确示例：

css 复制代码

/* ======================
   导航栏样式
   ====================== */
.nav {
  /* ... */
}

错误示例：

css 复制代码

/* 导航栏 */
.nav {
  /* ... */
}
/* 缺乏视觉分隔，不够醒目 */

正确示例：

css 复制代码

/* 使用flex布局实现垂直居中 */
.center-container {
  display: flex;
  align-items: center;
  justify-content: center;
}

错误示例：

css 复制代码

.center-container {
  display: flex;
  align-items: center; /* 居中 */
  justify-content: center; /* 居中 */
}
/* 冗余注释，没有提供额外信息 */

正确示例：

css 复制代码

/* TODO: 需要优化移动端显示效果 */
.responsive-card {
  width: 100%;
}

错误示例：

css 复制代码

.responsive-card {
  width: 100%; /* 需要修改 */
}
/* 不够明确，容易遗漏 */

SCSS支持两种注释方式，但编译后只有/* */会保留。

scss 复制代码

/* 这个注释会出现在编译后的CSS中 */
// 这个注释只会在SCSS中可见

scss 复制代码

/* 混合宏：创建圆角
----------------------------------- */
@mixin rounded-corners($radius) {
  // 参数：圆角半径
  border-radius: $radius;
}
/* 混合宏注释应该更详细说明参数和用法 */

考虑使用CSS注释生成文档工具，如cssdoc，需要遵循特定格式：

正确示例：

css 复制代码

/**
 * @section 按钮
 * @description 网站所有按钮的基础样式
 * 
 * @example
 *   <button class="btn">点击我</button>
 */
.btn {
  /* ... */
}

良好的CSS/SCSS注释应：

通过遵循这些规范，可以显著提高样式表的可维护性和团队协作效率。