程序员代码编写规范工作手册（标准版）

程序员代码编写规范工作手册（标准版）第一章总则1.1目的为统一团队代码编写标准，提升代码可读性、可维护性、可扩展性和安全性，降低开发成本、减少潜在Bug、提高团队协作效率，规范代码评审、版本控制及测试流程，确保交付高质量、符合行业最佳实践的软件产品，特制定本手册。本手册适用于所有开发人员（含前端、后端、移动端、嵌入式开发）及相关技术人员，是代码编写、评审、优化的核心依据。1.2适用范围本规范适用于公司所有软件开发项目（包括新项目开发、现有项目迭代、代码重构、Bug修复），覆盖所有编程语言（如Java、Python、JavaScript、C++、Go等），涵盖代码编写、注释、格式、命名、版本控制、测试、安全等全流程，所有参与项目开发的人员必须严格遵守，特殊场景需经技术负责人审批后方可偏离规范。1.3规范依据本规范基于行业通用标准及最佳实践制定，主要参考依据包括：PEP8（Python编码规范）、GoogleJavaStyleGuide（Java编码规范）、MicrosoftCStyleGuide（C语言编码规范）、AirbnbJavaScript风格指南，以及ISO/IEC12207（软件生命周期过程）相关要求，结合公司项目实际场景优化完善，确保规范的实用性和通用性。1.4术语定义代码风格：指代码的格式化规则，包括缩进、命名、注释、行宽等，直接影响代码可读性和协作效率。代码审查：通过同行评审发现代码中的缺陷、不符合规范之处，确保代码质量的过程。静态分析：使用工具（如ESLint、Pylint、SonarQube）自动检测代码中的语法错误、逻辑问题及规范偏离情况。硬编码：在代码中直接嵌入固定值（如密码、API密钥、常量等），不符合规范且存在安全风险，应避免使用。重构：在不改变代码功能的前提下，优化代码结构、简化逻辑、提升可读性，符合规范要求的代码优化行为。可维护性：代码易于修改、扩展、调试的能力，是规范编写的核心目标之一。第二章通用编码规范2.1命名规范命名核心原则：简洁、清晰、具有描述性，能够直观反映变量、函数、类、常量等的用途，避免使用无意义、模糊或易混淆的名称，遵循“见名知意”原则，禁止使用拼音、缩写（通用缩写如id、URL、API除外）。2.1.1变量命名采用驼峰命名法（camelCase），首字母小写，后续每个单词首字母大写，如userName、totalAmount、orderList。禁止使用单个字母（如a、b、c）或无意义名称（如temp、data），除非是局部循环变量（如for循环中的i、j，且作用域仅限循环内部）。布尔类型变量命名需体现“是否”含义，建议前缀使用is、has、can，如isActive、hasPermission、canEdit。避免使用关键字、保留字作为变量名，如class、int、function、let等。2.1.2常量命名采用全大写字母+下划线分隔（UPPER_SNAKE_CASE），如MAX_COUNT、PI、API_KEY、MAX_TIMEOUT。常量需集中定义，避免分散在代码中重复定义，确保值的统一性和可维护性。常量名称需明确体现其含义和用途，避免模糊命名，如ERROR_CODE_404（而非ERROR_404）。2.1.3函数/方法命名采用驼峰命名法（camelCase），首字母小写，以动词或动词短语开头，清晰描述函数功能，如getData、calculateTotal、fetchUserInfo、saveOrder。函数名称应简洁明了，避免过长（建议不超过20个字符），避免模糊表述，如避免使用doSomething、handleData等无明确含义的名称。查询类函数建议前缀使用get、fetch，修改类函数前缀使用set、update，删除类函数前缀使用delete、remove，判断类函数前缀使用is、has，如getUserById、updateUserName、deleteOrder、isValidUser。2.1.4类/接口命名采用帕斯卡命名法（PascalCase），首字母大写，后续每个单词首字母大写，以名词或名词短语命名，如UserProfile、DatabaseConnection、OrderService、FetchDataApi。类名需体现其核心职责，遵循单一职责原则，如UserService负责用户相关业务，OrderDao负责订单数据操作。接口命名建议前缀使用I（可选，根据团队习惯统一），如IUserService、IFetchData，清晰区分接口与实现类。2.1.5包/模块/文件命名包名（如Java、Python包）采用全小写字母，多个单词用点分隔，简洁且与功能相关，避免大写和下划线，如ject.user、mon。模块名、文件名遵循对应语言规范，如JavaScript文件采用驼峰命名，Python文件采用全小写+下划线分隔，如userService.js、user_utils.py。文件名称需与文件内核心内容一致，如UserController.java对应用户控制器类，orderList.vue对应订单列表组件。2.2代码格式规范2.2.1缩进统一使用4个空格作为缩进单位，禁止使用制表符（Tab），避免不同编辑器显示格式不一致。每层嵌套增加一个缩进（4个空格），确保代码层级清晰，如if、for、while循环、函数体、类体等均需缩进。续行缩进需与上一行相关代码对齐，可采用悬挂缩进（额外增加4个空格），如函数参数过多时，后续参数缩进对齐，提升可读性。2.2.2行宽限制单条代码行长度建议不超过120个字符，最长不超过150个字符，避免超长行导致阅读困难。若一行代码过长，需合理拆分，拆分原则：在运算符、逗号后拆分，拆分后每行逻辑相关，且缩进对齐，如复杂条件判断、函数参数、链式调用等。示例：正确拆分方式

//正确

Stringresult=fetchData()

.filter(item->item.getStatus()==ActiveStatus.ACTIVE)

.map(Item::getName)

.collect(Collectors.joining(","));

//错误（过长未拆分）

Stringresult=fetchData().filter(item->item.getStatus()==ActiveStatus.ACTIVE).map(Item::getName).collect(Collectors.joining(","));2.2.3空行与空格空行使用：类与类之间、函数与函数之间、逻辑块之间（如if块与else块、循环块与后续代码）需空1行，避免过多空行（连续空行不超过2行）。空格使用：

运算符（+、-、*、/、=、==、!=、&&、||等）两侧各加1个空格，如a=b+c、if(x==10)。逗号（,）、分号（;）后加1个空格，逗号前不加空格，如func(a,b,c)、for(inti=0;i<10;i++)。括号（()、{}、[]）内侧不加空格，外侧根据场景加空格，如if(condition)、List<String>list=newArrayList<>()。函数参数列表中，参数之间加1个空格，如publicvoidsaveUser(StringuserId,StringuserName)。禁止多余空格：行首、行尾不允许有多余空格，代码中间不允许有连续多个空格（除缩进外）。2.2.4大括号使用所有代码块（if、for、while、函数、类等）必须使用大括号包裹，即使代码块只有一行，避免省略大括号导致逻辑错误。大括号放置规范：左大括号（{）紧跟语句末尾，不独占一行；右大括号（}）独占一行，且与对应语句对齐，如：

//正确

if(isValid){

doSomething();

}else{

doAnotherThing();

}

//错误（左大括号独占一行）

if(isValid)

{

doSomething();

}2.3注释规范注释核心原则：简洁、准确、必要，注释需与代码同步更新，避免冗余注释、错误注释，代码本身应尽可能清晰，注释仅用于解释复杂、晦涩或不直观的逻辑，禁止注释掉的代码（无用代码直接删除）。2.3.1单行注释使用//开头，注释内容与//之间加1个空格，如//处理用户登录逻辑。单行注释需放在被注释代码的上方，或同一行右侧（右侧注释与代码之间至少加2个空格），避免注释与代码拥挤。避免每行代码都加注释，仅注释关键逻辑、特殊处理、边界条件等，如：

//由于数据库索引未优化，此处分批处理避免超时（关键注释）

for(inti=0;i<list.size();i+=100){

processBatch(list.subList(i,Math.min(i+100,list.size())));

}2.3.2多行注释使用/*...*/包裹，适用于注释多行内容，如类说明、复杂函数说明、代码块说明。多行注释格式：/*开头独占一行，注释内容每行缩进对齐，*/独占一行，如：/*

*用户信息类

*功能：存储用户基本信息（ID、姓名、手机号等），提供基础的get/set方法

*作者：开发团队

*/

publicclassUserInfo{

//类内容

}2.3.3文档注释适用于类、函数、接口，采用规范的文档注释格式（如Java的Javadoc、Python的docstring），说明其用途、参数、返回值、异常、作者、版本等信息。函数文档注释示例（Java）：/**

*计算订单总价（不含税）

*@paramitems商品列表，包含商品单价和数量

*@return订单总价，单位为分

*@throwsIllegalArgumentException当商品列表为空或商品信息不合法时抛出

*/

publicintcalculateOrderTotal(List<OrderItem>items){

//函数内容

}类文档注释需包含类的功能、核心职责、作者、创建日期等；接口文档注释需说明接口用途、实现要求等。2.3.4特殊注释待办事项：使用//TODO:标注，说明待完成的功能、优化点，如//TODO:优化Redis缓存命中率。问题标注：使用//FIXME:标注，说明代码中存在的问题、待修复的Bug，如//FIXME:此处可能出现空指针异常，需增加非空判断。特殊标记需定期清理，避免长期遗留，TODO需明确责任人（可选）和完成时间（可选）。第三章代码结构规范3.1核心原则单一职责原则（SRP）：每个函数、类、模块仅负责一项功能，避免功能冗余，如一个处理用户认证的类不应同时处理订单逻辑。DRY原则（避免重复代码）：不重复编写相同或相似的代码，将重复逻辑提取为函数、工具类或公共模块，减少冗余，便于维护。低耦合、高内聚：模块之间尽量减少依赖，模块内部逻辑紧密相关，便于扩展和修改。避免过度嵌套：代码嵌套层级不超过3层，超过3层需拆分逻辑，提取为子函数，避免逻辑混乱，提升可读性。3.2函数/方法结构函数长度：单个函数代码行数不超过50行（复杂逻辑可适当放宽，但不超过100行），函数功能单一，避免“大函数”。参数数量：函数参数不超过5个，超过5个时，建议使用对象封装参数（如Java的DTO、Python的字典），提升代码简洁度。返回值：返回值类型明确，避免返回null（必要时返回空集合、空对象，或使用Optional类型），返回值含义清晰，避免歧义。早返回原则：对于条件判断，尽量使用早期返回，避免过多嵌套，如：

//正确（早返回）

publicbooleancheckUser(Useruser){

if(user==null){

returnfalse;

}

if(user.getStatus()!=UserStatus.ACTIVE){

returnfalse;

}

returnuser.getAge()>=18;

}

//错误（过度嵌套）

publicbooleancheckUser(Useruser){

if(user!=null){

if(user.getStatus()==UserStatus.ACTIVE){

if(user.getAge()>=18){

returntrue;

}else{

returnfalse;

}

}else{

returnfalse;

}

}else{

returnfalse;

}

}3.3类结构类的成员顺序：静态常量→静态变量→成员变量→构造函数→公共方法→私有方法，确保结构清晰，便于查找。成员访问权限：严格控制访问权限，优先使用private（私有），必要时使用protected（受保护），避免随意使用public（公共），减少耦合。避免类过大：单个类代码行数不超过500行，超过时需拆分类，按功能拆分多个子类或模块。构造函数：避免构造函数逻辑过于复杂，复杂初始化逻辑提取为init()方法，构造函数仅负责成员变量的初始化。3.4模块/文件结构模块划分：按功能划分模块，如用户模块、订单模块、支付模块、工具模块等，模块内文件按类型分类（如controller、service、dao、entity）。文件内容：单个文件仅包含一个类（或一个核心功能模块），避免一个文件包含多个不相关的类或逻辑，便于维护和复用。依赖管理：模块之间的依赖需清晰，避免循环依赖，必要时通过接口解耦。第四章各语言专项规范4.1Java语言规范遵循GoogleJavaStyleGuide，类名采用PascalCase，方法、变量采用camelCase，常量采用UPPER_SNAKE_CASE。包名采用全小写，以公司域名倒置开头，如ject.user。避免使用null，优先使用Optional类处理可能为null的情况，减少空指针异常。异常处理：捕获异常后需处理（如日志记录），避免空catch块；自定义异常需继承Exception或RuntimeException，命名以Exception结尾，如UserNotFoundException。集合使用：指定集合泛型，避免使用原始类型（如List而非List）；优先使用ArrayList、HashMap等常用集合，避免使用Vector、Hashtable等低效集合。4.2Python语言规范严格遵循PEP8规范，缩进使用4个空格，行宽不超过120字符。命名规范：变量、函数采用snake_case（全小写+下划线分隔），类采用PascalCase，常量采用UPPER_SNAKE_CASE。导入规范：导入顺序为标准库→第三方库→自定义库，导入语句单独成行，避免导入无用模块；使用from...import...时，避免通配符（*）导入。文档字符串：使用三引号（"""..."""）编写文档注释，函数、类、模块开头必须添加文档字符串，说明用途、参数、返回值等。避免使用全局变量，必要时使用模块级变量；函数参数尽量使用位置参数，复杂参数使用关键字参数。4.3JavaScript/TypeScript规范遵循AirbnbJavaScript风格指南，变量、函数采用camelCase，类采用PascalCase，常量采用UPPER_SNAKE_CASE。变量声明：优先使用const（常量）、let（变量），禁止使用var（避免变量提升导致的问题）。箭头函数：适用于简单回调函数，避免this指向问题；复杂逻辑建议使用普通函数。TypeScript规范：严格指定类型，避免使用any类型；接口（interface）命名采用PascalCase，类型别名（type）命名采用PascalCase。代码格式化：使用ESLint、Prettier自动格式化代码，统一代码风格；避免使用eval()、with()等危险方法。4.4其他语言规范C++、Go、PHP等其他语言，遵循对应语言的行业标准规范，核心原则与本手册通用规范一致，具体细节由技术负责人结合项目实际制定补充规范。第五章安全编码规范5.1输入验证所有用户输入（如表单提交、接口参数、URL参数）必须进行验证，包括数据类型、长度、格式、范围等，避免非法输入导致安全问题。防止SQL注入：使用参数化查询（如PreparedStatement、ORM框架），禁止拼接SQL语句；避免直接将用户输入作为SQL语句的一部分。防止XSS攻击：对用户输入的HTML、JavaScript内容进行转义处理，避免恶意脚本执行；使用安全的前端渲染方式。5.2敏感信息处理禁止硬编码敏感信息，如密码、API密钥、数据库连接信息、Token密钥等，需存储在配置文件、环境变量或安全存储服务中。敏感数据传输：使用HTTPS协议传输敏感数据（如用户密码、支付信息），避免明文传输。敏感数据存储：用户密码需进行加密存储（如使用MD5、SHA256哈希+盐值，或使用加密算法），禁止明文存储。5.3资源安全资源释放：文件、数据库连接、网络连接、流等资源使用后必须及时关闭，避免资源泄漏；可使用try-with-resources（Java）、with语句（Python）自动释放资源。权限控制：严格控制代码访问权限，如文件读写权限、数据库操作权限，避免越权访问；接口访问需进行身份验证、权限校验。防止CSRF攻击：接口请求需添加CSRF令牌，验证请求的合法性，避免跨站请求伪造。5.4其他安全要求避免使用不安全的加密算法（如DES），优先使用AES、RSA等安全加密算法。日志记录：避免在日志中打印敏感信息（如密码、身份证号），日志内容需规范，便于排查问题。定期检查代码安全漏洞，使用安全扫描工具（如SonarQube）检测潜在安全问题，及时修复。第六章版本控制规范6.1版本控制工具统一使用Git作为版本控制工具，遵循Git工作流（如GitFlow、GitHubFlow），确保代码提交、分支管理、合并规范有序。6.2分支管理主分支（main/master）：用于存放正式发布的代码，禁止直接在主分支上提交代码，仅通过合并请求（MR/PR）更新。开发分支（develop）：用于日常开发，所有开发人员在开发分支上进行开发，或基于开发分支创建feature分支。功能分支（feature/*）：用于开发单个功能，命名格式为feature/功能名称（如feature/user-login），功能开发完成后，提交MR/PR合并到develop分支。修复分支（bugfix/*）：用于修复开发中的Bug或线上Bug，命名格式为bugfix/Bug描述（如bugfix/login-error），修复完成后合并到develop分支，线上Bug修复后需同步合并到main分支。发布分支（release/*）：用于版本发布准备，命名格式为release/版本号（如release/v1.0.0），发布完成后合并到main分支和develop分支。6.3提交规范提交频率：频繁提交，每次提交仅包含一个功能点或一个Bug修复，避免一次性提交大量无关代码，便于回溯和回滚。提交信息格式：统一使用“类型:描述”格式，类型包括feat（新增功能）、fix（修复Bug）、docs（文档更新）、refactor（代码重构）、style（格式修改，不影响逻辑）、test（增加/修改测试）、chore（构建/依赖更新），如：

feat:新增用户登录功能fix:修复用户登录时密码加密异常问题docs:更新接口文档提交描述：简洁明了（不超过50字符），准确描述提交内容，避免模糊表述（如“修改代码”“修复问题”）；复杂提交可添加详细描述（换行后编写）。提交前检查：提交前需检查代码是否符合本规范，是否存在语法错误、逻辑错误，是否完成测试，避免提交错误代码。6.4合并规范合并请求（MR/PR）：功能开发、Bug修复完成后，提交MR/PR，指定审核人，审核通过后才能合并代码。代码冲突：合并前需解决代码冲突，冲突解决后需重新测试，确保代码正常运行。合并后清理：分支合并完成后，及时删除对应的feature、bugfix分支，保持分支整洁。第七章测试与调试规范7.1测试规范单元测试：每个函数、类需编写单元测试，覆盖核心逻辑、边界条件、异常场景，单元测试覆盖率不低于80%，优先使用测试框架（如JUnit、pytest、Jest）。集成测试：模块开发完成后，进行集成测试，验证模块之间的交互是否正常，避免模块间接口冲突。测试代码规范：测试代码与业务代码分开存放，命名规范（如测试类命名为XXXTest），测试方法命名清晰，体现测试场景，如testUserLoginSuccess、testUserLoginFailWithWrongPassword。禁止跳过测试：提交代码前必须执行单元测试、集成测试，确保测试通过，避免将未测试的代码合并到开发分支或主分支。7.2调试规范调试工具：优先使用IDE调试工具（如IntelliJIDEA、PyCharm），避免使用System.out.println、print等临时调试语句，调试完成后删除临时调试代码。日志调试：使用日志框架（如Log4j、SLF4J、logging）记录调试信息，日志级别合理（DEBUG、INFO、WARN、ERROR），避免日志过多或过少。调试流程：调试前明确问题场景，定位问题根源，避免盲目调试；调试完成后，总结问题原因和解决方法，便于后续避免类似问题。第八章代码评审规范8.1评审流程代码提交：开发人员完成功能开发或Bug修复后，提交MR/PR，填写评审申请，指定1-2名审核人（技术骨干或负责人）。评审检查：审核人在24小时内完成评审，重点检查代码是否符合本规范、逻辑是否正确、是否存在安全隐患、是否完成测试、注释是否完整。问题反馈：审核人发现问题后，在MR/PR中备注问题，反馈给开发人员，开发人员及时修改。重新评审：开发人员修改完成后，重新提交评审，审核人确认问题已解决后，通过评审。合并代码：评审通过后，由审核人或开发人员合并代码，合并后删除对应分支。8.2评审标准规范符合性：代码是否符合本手册所有规范（命名、格式、注释、结构等）。逻辑正确性：代码逻辑是否清晰、正确，是否实现预期功能，是否存在逻辑漏洞。可读性与可维护性：代码是否易读、易理解，注释是否完整、准确，结构是否合理，便于后续修改和扩展。安全性：是否存在安全隐患（如SQL注入、XSS、敏感信息泄露等）。测试完整性：是否编写单元测试、集成测试，测试是否覆盖核心场景，测试是否通过。性能优化：是否存在性能问题（如冗余计算、循环效率低、资源泄漏等），是否有优化空间。8.3评审注意事项评审人需客观、严谨，聚焦代码质量，避免个人主观判断，提出的问题需具体、可修改。开发人员需积极配合评审，及时修改问题，不推诿、不敷衍；对评审意见有异议的，可与评审人沟通协商。评审记录：所有评审意见、修改记录