代码编写规范文档

代码编写规范精选文档代码编写规范的核心目标是保证代码的可读性、可维护性、可复用性和一致性，降低团队协作成本与后期维护成本，同时提升代码质量、减少Bug产生。本文档精选通用规范与主流编程语言核心规范，兼顾通用性与实用性，适用于个人开发及团队协作场景，可直接落地执行。一、通用核心规范（全语言适用）1.1命名规范（基础且核心）命名的核心原则是“见名知意”，禁用拼音、无意义缩写（通用缩写如id、URL、API除外），统一命名风格，避免大小写混乱，具体要求如下：变量/函数：采用小驼峰命名法（camelCase），如userName、calculateTotalAmount，避免单个字母（如a、b）或模糊命名（如data1、temp）。常量：采用全大写+下划线分隔（UPPER_SNAKE_CASE），如MAX_CONNECTIONS、API_TIMEOUT，明确常量含义，避免魔法数字/字符串硬编码。类/结构体：采用大驼峰命名法（PascalCase），如DatabaseConnection、UserService，类名需体现其核心职责。私有成员：前缀加下划线（_xxx），如_privateMethod、_connection，区分公共与私有成员，避免访问冲突。文件/目录：前端优先采用小写+连字符（kebab-case），如user-service.js；后端可采用小写+下划线或小驼峰，统一即可，如data_processor.py、userController.java。1.2注释规范（拒绝冗余，精准实用）注释的核心是“解释为什么做，而非做了什么”，避免冗余注释、过时注释，确保注释与代码同步更新，具体要求如下：类/接口/公共方法：必须添加文档注释（如Java的Javadoc、Python的Docstring），说明功能、参数、返回值、异常场景及作者信息。复杂逻辑：针对算法、特殊业务规则、难以理解的代码块，添加行注释，解释设计思路和核心逻辑，避免“看代码猜意图”。临时代码：标注//TODO:待优化（说明优化方向）或//FIXME:修复XX问题（说明问题详情），避免遗留未处理代码。禁止项：禁止注释代码本身（如//声明变量userName）、禁止过时注释（代码修改后未同步更新注释）、禁止长篇大论注释（注释长度不超过对应代码长度）。1.3格式规范（保持一致性，提升可读性）缩进：统一使用空格缩进（禁止混合使用空格与制表符），Python固定4个空格，JavaScript常用2个空格，Java常用4个空格，团队内统一标准。行宽：单行车代码长度不超过80-120个字符（根据语言特性调整），超长行需合理换行，避免横向滚动查看。空行：逻辑块之间（如函数之间、类之间、循环与条件判断之间）添加1个空行，区分代码层级；禁止连续多个空行，禁止文件末尾留空行。空格：运算符（+、-、*、/、=等）两侧、逗号后各加1个空格；括号内侧（如if()、for()）不加空格，如if(condition)而非if(condition)。1.4代码结构规范（单一职责，简洁可维护）单一职责：每个函数、类仅负责一件事，函数长度控制在80行以内，类长度控制在1000行以内，复杂逻辑拆分至子函数/子模块。嵌套层级：if、for、while等循环/条件判断的嵌套不超过3层，超过则拆分函数，避免代码晦涩难懂。避免重复：遵循DRY原则（Don'tRepeatYourself），重复代码提炼为公共函数/工具类，减少冗余，便于统一维护。早返回原则：条件判断中，优先返回不符合条件的场景，减少嵌套层级，如if(!valid)return;而非嵌套if(valid){...}。1.5异常与安全规范（规避风险，稳健运行）异常处理：捕获具体异常（如IOException、DataProcessingError），禁止捕获万能异常（如Exception）；异常需有明确处理逻辑（日志记录、错误提示），不吞异常。安全防护：禁止硬编码敏感信息（密码、API密钥等），需存入配置文件或环境变量；对用户输入进行校验，防止SQL注入、XSS攻击等。资源释放：文件、数据库连接、网络连接等资源使用后必须关闭，避免资源泄漏；可使用try-finally或自动关闭语法（如Java的try-with-resources）。二、主流编程语言核心规范（精选重点）2.1Python规范（遵循PEP8标准）缩进：严格使用4个空格，禁止使用制表符，缩进不一致会直接导致语法错误。导入规范：导入语句放在文件顶部，先导入标准库，再导入第三方库，最后导入本地模块；禁止使用通配符导入（如frommoduleimport*）。命名补充：模块和包名采用全小写+下划线（如data_processor），类名大驼峰，函数/变量小驼峰，常量全大写。代码示例：

defprocess_data(input_data,max_retries=3):

"""处理输入数据并返回结果（Docstring注释）

Args:

input_data:要处理的数据

max_retries:最大重试次数，默认为3

Returns:

处理后的数据结果

"""

try:

result=transform_data(input_data)

returnnormalize_result(result)

exceptDataProcessingErrorase:

ifmax_retries>0:

returnprocess_data(input_data,max_retries-1)

raise#重新抛出异常，不吞异常工具支持：使用pylint、flake8进行代码规范检查，自动识别不符合PEP8的代码。2.2JavaScript规范（遵循Airbnb风格）缩进：常用2个空格，函数、条件判断的大括号采用K&R风格（左括号紧跟语句，右括号单独成行）。命名补充：变量/函数小驼峰，构造函数/类名大驼峰，常量全大写+下划线，私有成员前缀下划线。语法规范：字符串优先使用单引号；箭头函数用于简单回调，避免this指向混乱；变量声明优先使用const、let，禁止使用var。代码示例：

//常量定义

constAPI_TIMEOUT=5000;

constMAX_RETRY_ATTEMPTS=3;

//类定义

classUserService{

constructor(){

this._connection=null;//私有成员

}

//方法定义

getUserProfile(userId){

if(!userId){

thrownewError('用户ID不能为空');

}

//业务逻辑

returnfetch(`/api/user/${userId}`);

}

}工具支持：使用ESLint、Prettier自动格式化代码，统一代码风格。2.3Java规范（遵循GoogleJavaStyle）缩进：使用4个空格，大括号采用K&R风格，类、方法、代码块之间添加合理空行。命名补充：包名全小写（如ject.service），类名/接口名大驼峰（接口名可加I前缀，如IUserService），方法名/变量名小驼峰，常量全大写+下划线。语法规范：布尔类型方法名前缀用is/has（如isUserActive、hasPermission）；参数校验优先使用注解（如@NotBlank、@NotNull），不手动if判断。代码示例：

packageject.service;

/**

*用户服务类，提供用户信息的增删改查功能（Javadoc注释）

*/

publicclassUserService{

//常量定义

publicstaticfinalintMAX_CONNECTION_POOL_SIZE=50;

//实例变量

privateStringuserName;

/**

*根据用户ID查询用户信息

*@paramuserId用户唯一标识

*@return用户信息对象

*/

publicUsergetUserById(intuserId){

if(userId<=0){

thrownewIllegalArgumentException("用户ID无效");

}

//数据库查询逻辑

returnuserDao.selectById(userId);

}

//布尔方法示例

publicbooleanisUserActive(intuserId){

Useruser=getUserById(userId);

returnuser!=null&&user.getStatus()==1;

}

}工具支持：使用Checkstyle、PMD进行静态代码分析，IDEA可配置GoogleJavaStyle模板自动格式化。三、工程化落地规范（团队协作必备）3.1版本控制规范提交信息格式：类型(模块):描述（简洁明了，不超过50字），如feat(user):新增用户注册功能、fix(login):修复登录令牌过期bug。提交频率：频繁提交（每完成一个小功能、修复一个bug即提交），避免长时间不提交，便于回溯和问题定位。分支管理：主分支（main/master）保持稳定，开发分支（develop）用于日常开发，功能分支（feature/xxx）用于单个功能开发，修复分支（hotfix/xxx）用于线上bug修复。3.2工具与自动化规范统一工具：团队统一使用相同的代码格式化工具、静态检查工具，配置统一的规范模板，避免风格差异。自动化校验：集成CI/CD流程，提交代码时自动执行规范检查和单元测试，不符合规范的代码禁止合并。单元测试：核心函数、工具类必须编写单元测试，代码覆盖率不低于80%，确保代码功能正确。四、禁忌与注意事项禁止使用拼音、中文命名，禁止无意义命名（如abc、test1），禁止大小写混乱。禁止注释代码、过时注释、冗余注释，禁止代码与注释不一致。禁止嵌套过深、函数/类过长，禁止重复代码，禁止硬编码敏感信息。禁止捕获万能异常、吞