编码规范文档最佳实践：让团队协作更高效

为什么需要编码规范文档

刚进新公司时，我接手了一个老项目。打开代码一看，有人用单引号，有人用双引号；缩进一会儿两个空格，一会儿四个空格，甚至还有用 tab 的。函数命名一会儿驼峰，一会儿下划线。读代码像在破案，调试半小时，定位问题两小时。

后来我们定了编码规范文档，统一了风格。新人上手快了，Code Review 也轻松了。这不是追求强迫症式的整齐，而是为了降低沟通成本。

一份实用的规范长什么样

规范不是写给理想世界的，是为了解决真实问题。比如 JavaScript 项目，可以这样定：

// 使用 ESLint 配置强制执行
{
  "extends": ["eslint:recommended"],
  "rules": {
    "quotes": ["error", "single"],
    "indent": ["error", 2],
    "camelcase": "error"
  }
}

CSS 也可以简单明了：

/* 类名使用 kebab-case */
.user-profile-card { }

/* 避免嵌套过深 */
.header {
  margin: 0 auto;
  
  &__logo {
    width: 100px;
  }
}

别只写规则，附上例子

“变量命名要语义化”这种话太模糊。不如直接写：

✅ 推荐：const maxLoginAttempts = 3;
❌ 不推荐：const limit = 3;

图文并茂更好理解。比如展示组件结构时，配个小图或代码块，比一整段文字描述清楚得多。

如何推动落地

写完文档扔群里，没人看。真正有效的是把它变成流程的一部分。

我们在 CI 流程里加了 Lint 检查，提交代码自动跑一遍。不合规范？直接拒绝合并。一开始有人抱怨，但两周后大家都习惯了。就像系安全带，开始觉得麻烦，后来成了自然动作。

另外，在项目初始化脚手架里内置配置。新项目一键生成，规则自动带上。省得每个人重复配置。

定期回顾和更新

半年前我们规定禁用 var，全部用 const 和 let。现在回头看，这条已经成了常识。而新的问题出现了：异步函数要不要统一加 async 前缀？于是我们在规范里新增了一条建议，并附上讨论记录。

规范不是法律，是活的文档。每隔一个版本迭代，拉核心成员过一遍，删掉过时的，补上新坑的教训。

小团队也能用得上

别说自己人少就不用规范。两个人合作，一样会有风格冲突。我见过创业团队因为“括号换不换行”吵到 Slack 爆炸。

哪怕只有三五个人，花一小时写下基本约定，远比事后扯皮强。可以从最痛的点入手：比如统一文件结构、日志格式、注释方式。

关键是把文档放在大家每天都能看到的地方——GitHub Wiki、Notion 页面，或者项目根目录下的 CONTRIBUTING.md。别藏在某个角落等别人“主动去学”。