开源代码规范该如何制定？

本文目录导读：

1. Naming Conventions
2. Code Structure
3. Commit Convention
4. Testing

制定开源代码规范是一项系统工程,其核心目标是降低协作门槛、保证代码一致性、提升可维护性，并为社区贡献者提供清晰的指引。

一份好的规范不是“管人”的，而是“帮人”的，以下是一套从顶层设计到具体落地的完整制定指南：

第一步：明确核心原则（定基调）

在开始写具体规则前,团队需要先达成几个共识：

1. 自动化优先：能用工具（linter、formatter）强制执行的，绝不写在文档里，规则应尽量是自动提示的，而非人工审查的。
2. 最小共识原则：只规定必须统一的点（如缩进、命名风格），避免过度规定（如“函数必须控制在30行以内”这种非强制建议）。
3. 有据可依：每个规则最好能给出理由（使用 const 而不用 var，因为可以避免变量提升导致的bug”）。
4. 拥抱社区标准：优先采用该语言社区公认的主流规范（如 Python PEP 8、JavaScript Standard Style），避免自创奇葩规则。

第二步：规范的核心内容模块（写什么）

一份完善的规范文档通常包含以下模块：

通用代码风格（语言无关）

• 缩进：空格还是Tab？如果是空格，是2个还是4个？
• 行尾：LF（Unix/Mac）还是CRLF（Windows）？建议强制统一为LF。
• 文件末尾：是否需要一个空行？（这是POSIX标准，通常需要）
• 最大行长：通常建议80-120字符（避免横向滚动）。
• 空白字符：禁止尾随空格（trailing whitespace）。

特定语言规则（以JavaScript/TypeScript为例）

• 命名规范：
  • camelCase：变量、函数、方法。
  • PascalCase：类、接口、类型、组件。
  • UPPER_SNAKE_CASE：全局常量、环境变量。
  • _private：私有属性前缀（虽然ES6有，但很多项目依然使用下划线）。
• 声明方式：优先 const，次之 let，禁止 var。
• 字符串：统一使用单引号、双引号还是反引号（模板字符串）？
• 分号：是否必须？推荐始终加，或使用自动分号插入（ASI）的规则。
• 异步处理：优先 async/await，禁止回调地狱；Promise 链式调用需合理换行。

代码组织与架构

• 文件命名：组件文件用 PascalCase（如 UserCard.tsx），逻辑文件用 kebab-case（如 user-service.ts）。
• 文件结构：一个文件最好只暴露一个主要功能（比如一个React组件）。
• 导入顺序：通常分为三类，空行隔开：
  1. 内置模块/第三方库（fs、react）。
  2. 内部模块（@/components/、./utils）。
  3. 相对路径父级（）。
• 注释规范：
  • 为什么要写：解释“为什么这么写”（业务逻辑、性能考虑），而不是“写的是什么”（好的代码本身应该自解释）。
  • 格式：使用工具可解析的注释（如 JSDoc、Pydoc），方便生成文档。
  • TODO/FIXME：标注待办和已知问题，并附上责任人。

分支管理与提交信息

• 分支命名：
  • feat/login-page
  • fix/user-auth-bug
  • chore/update-deps
• Commit Message 规范：推荐遵循 Conventional Commits 标准。
  • feat: 新增用户登录功能
  • fix: 修复空指针异常
  • docs: 更新README中的API说明
  • refactor: 重构用户验证逻辑，提取为公用函数

错误处理与日志

• 错误抛出：禁止抛出非 Error 对象（如 throw "error"），应使用 throw new Error(...)。
• 日志级别：明确 debug、info、warn、error 的使用场景。
• 异步错误：所有 Promise 都必须有 .catch() 或其等效的 try/catch。

测试规范（可选但强烈推荐）

• 测试文件命名：*.test.ts 或 *.spec.ts。
• 测试结构：遵循 AAA 模式（Arrange-Act-Assert）。
• 覆盖率要求：设定最低覆盖率红线（如80%）。

第三步：落地执行机制（怎么用）

光写文档没用,必须通过工具和流程强制落地：

1. 自动化工具配置（最关键的一步）：

   • 格式化：使用 Prettier（前端）、Black（Python）、gofmt（Go）等，并集成到保存文件自动运行中。
   • 静态检查：使用 ESLint、Pylint、SonarQube 等，配置中要将大部分规则设为 error（错误），意味着CI中会阻断构建。
   • 配置文件：统一将配置放在 eslint.config.js、.prettierrc、pyproject.toml 等文件中，并提交到仓库。

2. Git Hook（本地屏障）：

   • 使用 Husky 或 Lefthook 配置 pre-commit 钩子，在提交前自动运行 lint-staged（只检查本次改动的文件），不符合规则则禁止提交。

3. 持续集成/持续部署（CI）检查：

   • 在 GitHub Actions、GitLab CI、Jenkins 中，设置 Job 在每次 PR 时运行 lint、format 检查和单元测试。
   • 未通过拉取请求（PR）检查的代码不得合并。

4. 评审流程（Code Review）：

   • 在 PR 模板中放一份 Checklist（如：[ ] 代码通过了lint检查，[ ] 所有新功能都有测试）。
   • 审查者除了检查逻辑,也要关注是否遵守规范，如果逻辑有问题但规范过了，建议直接通过；如果逻辑完美但规范有问题（非自动检查），也可视为不通过。

一份优秀的开源规范文档应该像这样写

# Project Code Style Guide
## 1. Philosophy
- 自动化高于文档，配置即文档。
## 2. Tool Configuration
- 使用 `ESLint` + `@xxx/config` (已发布到npm)
- 使用 `Prettier` (配置文件见 `.prettierrc`)
- 在 `package.json` 中配置命令：
  ```bash
  npm run lint # 检查
  npm run format # 自动修复

Naming Conventions

• 组件/类：PascalCase -> UserProfile
• 变量/函数：camelCase -> getUserData
• 常量：UPPER_SNAKE_CASE -> MAX_RETRY_COUNT

Code Structure

• 一个文件只导出一个主要组件/函数。
• 导入顺序：React -> 第三方 -> 内部模块 -> 样式。

Commit Convention

• 遵循 Conventional Commits.
• 所有提交必须通过 commitlint 检查。

Testing

• 使用 Jest + Testing Library.
• 测试文件需与被测文件同目录,命名为 *.test.tsx.
• 行覆盖率不低于 80%。

避坑指南（不做这些）

• ❌ 不要用Word/PDF写规范：难维护、难检索，必须写在代码仓库的 CONTRIBUTING.md 或 STYLE_GUIDE.md 中。
• ❌ 不要制定无法自动检查的规则：如“变量名要有意义”、“代码不要太复杂”，这些交给Code Review。
• ❌ 不要一刀切：对于历史遗留项目，可以设定一个 “新人遵守新规则，旧代码逐步重构” 的过渡期。
• ❌ 不要只有一人拍脑袋：规范应该是核心维护者讨论的结果，并接受社区意见（开Issue讨论）。

推荐一个业界标杆： 参考 Google 的开源风格指南（如 Google JavaScript Style Guide），它结构清晰、理由充分，是极佳的模板，然后基于此，删减你不需要的，增补你独有的即可。