软件开发工程师代码规范工作手册

软件开发工程师代码规范工作手册前言本手册旨在统一团队编码标准，规范软件开发流程中的代码编写、评审、提交、维护等全环节行为，提升代码可读性、可维护性、可扩展性与安全性，降低协作成本和后期维护成本，保障项目质量与交付效率。所有软件开发工程师（含前端、后端、移动端）在日常开发工作中，必须严格遵循本手册规定；若项目有特殊规范，需在本手册基础上补充说明，特殊规范优先级高于本手册通用要求。本手册将根据技术发展、团队需求迭代及项目实践反馈，定期更新优化，确保规范的实用性与前瞻性。第一章核心原则1.1可读性优先代码是写给人看的，其次才是给机器执行的。编写代码时，需保证逻辑清晰、命名规范、注释完整，确保团队任何成员都能快速理解代码意图，避免出现“只有作者能看懂”的情况。禁止使用晦涩难懂的缩写、无意义的变量名，避免过度简化代码逻辑而牺牲可读性。1.2可维护性原则代码需具备良好的可维护性，便于后续迭代、bug修复和功能扩展。遵循单一职责原则（SRP），每个模块、类、方法仅负责一项核心功能；避免代码重复，提取公共逻辑形成工具类或公共方法；合理使用设计模式，减少代码耦合，确保修改一处代码时，不会引发连锁反应。1.3可扩展性原则编码时需考虑未来需求变更，预留扩展空间。采用模块化设计，拆分独立子系统，子系统间通过接口通信；避免硬编码配置、固定逻辑，将可变参数、配置项抽离至配置文件；设计可参数化的接口，支持后续功能扩展而无需大规模修改核心代码。1.4安全性原则优先保障代码安全性，防范常见安全漏洞。敏感数据（密码、密钥等）必须加密存储与传输，禁止明文存储；严格校验输入参数，防范SQL注入、XSS、CSRF等常见漏洞；合理处理异常，避免泄露系统敏感信息；定期通过安全工具扫描代码，及时修复安全隐患。1.5一致性原则团队内所有成员需严格遵循本手册规范，保持代码风格、命名规则、注释格式、文件组织结构的一致性。禁止个人随意突破规范，若有规范不合理之处，需提交团队讨论后统一修改，不得擅自修改编码风格。第二章通用编码规范2.1命名规范2.1.1基本原则命名需简洁、准确、有意义，能够直接反映变量、类、方法、文件的用途，避免使用无意义的名称（如a、b、temp、test等）；禁止使用拼音、拼音缩写（通用拼音缩写如GDP、URL等除外），统一使用英文命名；避免使用关键字、保留字作为命名。2.1.2变量命名采用小驼峰命名法（camelCase），首字母小写，后续单词首字母大写，如userName、totalAmount、requestTimestamp。变量名需体现其数据类型或用途，如boolean类型变量以is、has开头（isLogin、hasPermission），集合类变量以list、map、array结尾（userList、orderMap）。禁止使用单个字母作为变量名（循环变量i、j、k除外，且循环嵌套不超过3层）。2.1.3常量命名采用全大写字母，单词之间用下划线分隔（UPPER_SNAKE_CASE），如MAX_CONNECTIONS、DEFAULT_TIMEOUT、PI。常量需定义在类的顶部或专门的常量类中，集中管理，禁止在代码中直接使用魔术数字、魔术字符串（如直接使用100、"success"等，需替换为常量）。2.1.4类/接口命名类名采用大驼峰命名法（PascalCase），首字母大写，后续单词首字母大写，如UserInfo、PaymentService、DatabaseConnection，类名需为名词或名词短语，体现类的核心功能。接口名同样采用大驼峰命名法，可在开头加I标识（如IPaymentService），也可直接使用功能名称，保持团队统一即可。2.1.5方法命名采用小驼峰命名法，首字母小写，后续单词首字母大写，方法名需为动宾结构，清晰体现方法的功能，如getUserInfo（获取用户信息）、calculateTotalPrice（计算总价）、saveToDatabase（保存到数据库）。查询类方法以get、find、select开头，修改类方法以set、update、modify开头，删除类方法以delete、remove开头，新增类方法以add、create开头。2.1.6文件/文件夹命名文件命名需与类名、功能保持一致，类文件以类名命名（如UserInfo.java、UserController.js）；工具类文件以Utils、Helper结尾（如StringUtils.java、DateHelper.js）；文件夹命名采用小写字母，单词之间用下划线分隔（如user_manage、common_utils），按功能模块划分文件夹（如controller、service、dao、model）。2.2代码格式规范2.2.1缩进与空格统一使用4个空格作为缩进（禁止使用制表符Tab），避免混合使用空格和制表符；代码块（if、for、while、class、method等）的左大括号{紧跟语句末尾，右大括号}单独占一行，与对应语句对齐，如：java

if(user!=null){

//代码逻辑

}else{

//代码逻辑

}运算符（+、-、*、/、==、!=、&&、||等）前后各加1个空格，如intresult=a+b;if(a==b){}；逗号（,）后加1个空格，如List<String>list=Arrays.asList("a","b","c")；分号（;）后加1个空格（一行多句时），但分号作为语句结束时，无需额外加空格。2.2.2行长度限制单条代码行长度控制在80-120个字符之间，超过限制时需换行，换行原则：在运算符后换行、在逗号后换行，换行后缩进比上一行多4个空格，确保代码对齐，如：java

StringuserInfo="用户名："+userName+"，手机号："+phoneNumber

+"，邮箱："+email+"，注册时间："+registerTime;2.2.3空行规范类的不同成员之间（属性与方法、方法与方法）加1个空行；方法内部不同逻辑块之间加1个空行；import语句与类定义之间加1个空行；注释与被注释代码之间无需加空行，但注释上方可根据需要加1个空行，提升可读性。禁止出现连续2个及以上空行，禁止行尾出现空格，禁止文件末尾出现空行。2.3注释规范2.3.1注释基本原则注释需简洁、准确、有用，避免冗余注释（如注释与代码完全一致）；注释语言统一使用中文，禁止使用英文、拼音或混合语言；注释需及时更新，代码修改后，对应注释必须同步修改，避免出现注释与代码不一致的情况；禁止保留注释掉的代码（无用代码直接删除，如需保留可通过版本控制工具回溯）。2.3.2类注释每个类的顶部必须添加类注释，使用文档注释格式（如Java的/***/、Python的"""""""），包含类的功能描述、作者、创建时间、修改记录（可选），如：java

/**

*用户信息类，用于封装用户的基本信息（用户名、手机号、邮箱等）

*负责用户信息的存储、获取与简单校验

*@author张三

*@date2026-03-25

*@version1.0

*/

publicclassUserInfo{

//类属性与方法

}2.3.3方法注释每个公共方法（public）的顶部必须添加方法注释，包含方法功能描述、参数说明（@param）、返回值说明（@return）、异常说明（@throws，如有），复杂方法需补充逻辑说明，如：java

/**

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

*@paramuserId用户ID，非空且为正整数

*@returnUserInfo用户详细信息，查询不到则返回null

*@throwsIllegalArgumentException当userId为null或非正整数时抛出

*/

publicUserInfogetUserInfo(LonguserId){

if(userId==null||userId<=0){

thrownewIllegalArgumentException("用户ID非法");

}

//查询逻辑

returnuserDao.selectById(userId);

}私有方法（private）可根据复杂度添加注释，简单方法无需注释，复杂逻辑必须添加注释说明逻辑意图。2.3.4代码行注释针对复杂逻辑、关键步骤、难以理解的代码行，需添加行注释（//注释内容），注释位于代码行上方或右侧，右侧注释与代码之间至少保留2个空格。禁止对简单、直观的代码添加行注释（如//定义变量a、//循环遍历列表），如：java

//计算用户总积分：基础积分+额外积分-扣除积分（特殊场景需优先扣除额外积分）

inttotalScore=baseScore+extraScore-deductScore;

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

Useruser=list.get(i);

//跳过禁用状态的用户（状态为0表示禁用）

if(user.getStatus()==0){

continue;

}

//处理用户逻辑

}2.3.5块注释用于注释一段代码块（如临时注释、逻辑说明），使用/*注释内容*/，块注释需与代码对齐，避免随意缩进，如：java

/*

*临时注释：该逻辑暂不启用，后续优化

*功能：批量更新用户状态

*待优化点：1.未处理异常2.未做批量限制

*/

/*

for(Useruser:userList){

user.setStatus(1);

userDao.update(user);

}

*/第三章各环节专项规范3.1编码实现规范3.1.1变量与数据类型变量必须先定义、后使用，禁止未定义直接使用；根据数据用途选择合适的数据类型，避免过度使用大类型（如用int代替long、用String代替boolean）；避免使用全局变量，如需共享数据，优先使用局部变量、参数传递或单例模式，减少全局状态带来的隐患；变量作用域最小化，仅在需要的范围内定义变量，避免跨范围使用。数据类型转换需安全，避免强制转换导致的类型异常，如int转long可直接转换，long转int需进行范围判断；字符串拼接优先使用StringBuilder（Java）、f-string（Python）等高效方式，避免频繁使用+拼接导致的性能损耗。3.1.2控制结构条件语句（if-else）：避免深层嵌套（嵌套不超过3层），超过3层需拆分方法或使用策略模式优化；if语句后即使只有一行代码，也必须添加大括号{}，避免逻辑错误；elseif需按逻辑顺序排列（如从小到大、从异常到正常），禁止无序排列；禁止使用if(flag==true)、if(flag==false)，直接使用if(flag)、if(!flag)。循环语句（for、while、do-while）：循环条件需清晰，避免出现死循环；循环体内逻辑尽量简洁，复杂逻辑拆分至单独方法；for循环用于固定次数的遍历，while循环用于不确定次数的遍历；禁止在循环体内修改循环变量（如for(inti=0;i<10;i++){i++;}），避免循环异常。switch语句：case后必须添加break（除了有意的穿透场景，需添加注释说明）；default分支必须存在，用于处理异常情况；switch表达式优先使用枚举类型，避免使用魔术数字；case语句需按顺序排列，相同逻辑的case可合并。3.1.3方法实现方法职责单一，每个方法仅实现一个核心功能，方法长度控制在50行以内，超过50行需拆分方法；方法参数个数控制在5个以内，超过5个需使用实体类、Map或Builder模式封装参数；禁止方法返回null（除非有明确说明），可返回空集合、空对象替代null，避免空指针异常；方法内禁止出现重复代码，重复逻辑需提取为公共方法。方法重载与重写：重载方法需保证参数个数、类型不同，功能一致；重写方法需遵循里氏替换原则，不能改变父类方法的核心功能和返回值类型；重写方法需添加@Override注解（如Java），明确标识重写关系。3.1.4异常处理异常处理需精准，避免捕获所有异常（如catch(Exceptione)），需针对性捕获具体异常（如NullPointerException、IllegalArgumentException）；异常捕获后需做具体处理（如日志记录、返回提示、数据回滚），禁止捕获异常后不做任何处理；禁止使用异常控制程序流程（如用try-catch代替if判断）。自定义异常：针对业务场景定义自定义异常，命名以Exception结尾（如UserNotFoundException），包含错误码、错误信息，便于异常定位和处理；抛出异常时需携带详细的错误信息，避免抛出空异常（newException()）。资源释放：使用文件、流、数据库连接等资源时，必须保证资源释放（如使用try-with-resources、finally块），避免资源泄露；流操作需按顺序关闭，先打开的后关闭。3.1.5类与对象类的设计遵循SOLID原则，单一职责、开放封闭、里氏替换、接口隔离、依赖倒置；类的属性私有化（private），通过getter/setter方法访问和修改，禁止直接访问属性；构造函数用于初始化属性，避免在构造函数中执行复杂逻辑（如数据库查询、网络请求）。对象创建与销毁：避免频繁创建对象（如在循环体内创建对象），可使用对象池、单例模式优化；及时释放无用对象，避免内存泄露（如集合中移除不再使用的元素、解除对象引用）；单例模式需保证线程安全，禁止双重检查锁定的不规范实现。3.2代码提交规范3.2.1提交前准备提交代码前，必须进行本地自检：检查代码是否符合本手册规范、功能是否正常实现、是否存在语法错误、是否通过单元测试；使用静态分析工具（如SonarQube、ESLint）扫描代码，修复发现的问题；拆分大型变更，单次提交代码量控制在400行以内，避免一次性提交大量代码，便于代码评审和问题定位。3.2.2提交信息规范提交信息（commitmessage）需简洁、准确、规范，采用“类型:描述”的格式，类型统一如下：feat：新增功能（如“feat:新增用户登录功能”）fix：修复bug（如“fix:修复用户登录密码加密异常问题”）docs：文档修改（如“docs:更新代码规范手册注释部分”）style：代码格式修改（不影响代码功能，如“style:调整代码缩进、删除空行”）refactor：代码重构（不新增功能、不修复bug，如“refactor:拆分用户查询方法”）test：新增/修改测试用例（如“test:新增用户登录单元测试”）chore：构建、依赖、工具相关修改（如“chore:更新依赖版本、配置打包脚本”）描述部分需简洁明了，说明提交的核心内容，避免模糊描述（如“修改代码”“修复问题”）；若提交涉及多个修改，可在描述后添加换行，补充详细说明（使用“-”开头），如：plaintext

feat:新增用户管理功能

-新增用户列表查询接口

-新增用户新增、编辑、删除接口

-优化用户信息校验逻辑禁止提交无意义的提交信息（如“test”“123”“更新”），禁止单次提交包含多个不相关的修改（如同时修改登录功能和订单功能）。3.2.3提交频率与分支规范提交频率：开发过程中，每完成一个小功能、修复一个bug、优化一段逻辑，都需及时提交代码，建议每天提交不少于2次，避免代码堆积；提交前需拉取（pull）最新代码，解决冲突后再提交，禁止直接提交导致冲突。分支规范：遵循GitFlow分支管理模式，核心分支包括：master/main：生产环境分支，仅用于发布，禁止直接在该分支提交代码；develop：开发分支，用于集成各功能分支，所有开发工作基于该分支创建子分支；feature/*：功能分支，用于开发新功能，命名格式为feature/功能名称（如feature/user-login），功能完成后合并至develop分支；bugfix/*：bug修复分支，用于修复测试环境、开发环境的bug，命名格式为bugfix/bug描述（如bugfix/login-password-error），修复完成后合并至develop分支；hotfix/*：紧急修复分支，用于修复生产环境的紧急bug，命名格式为hotfix/bug描述（如hotfix/payment-fail），修复完成后合并至master/main和develop分支。分支使用完毕后，及时删除（如feature分支合并至develop后，删除该feature分支），避免分支冗余。3.3代码评审规范3.3.1评审准备代码提交后，需发起代码评审（CodeReview），指定至少1名评审人（建议为模块负责人或资深工程师）；评审前，提交者需准备评审资料，包括提交说明、功能背景、测试情况、影响范围，标记关键修改点，便于评审人快速了解内容。评审人需在12-24小时内确认评审任务，评估自身专业匹配度，若不匹配需协调其他合适的评审人；评审前需通过静态分析工具扫描代码，提前发现基础格式、规范问题。3.3.2评审内容与标准评审需覆盖以下核心内容，确保代码符合规范、质量达标：功能正确性：代码是否实现需求，逻辑是否正确，边界条件是否覆盖，是否存在逻辑漏洞；规范符合性：是否遵循本手册的命名、格式、注释等规范，代码风格是否与团队一致；可读性与可维护性：代码逻辑是否清晰，命名是否准确，注释是否完整，是否存在重复代码、过度耦合；安全性：是否存在安全漏洞（如SQL注入、XSS、敏感数据泄露），输入参数是否校验，资源是否安全释放；性能：是否存在性能瓶颈（如N+1查询、频繁创建对象、死循环），是否有优化空间；测试覆盖：新增/修改代码是否配套单元测试，测试用例是否覆盖核心逻辑和边界条件。评审关注点分布建议：功能正确性占40%、代码可读性占25%、性能考量占15%、安全因素占12%、其他占8%，确保评审重点突出。3.3.3评审流程与反馈评审流程：评审人先通读代码，理解整体变更，再逐行细查逻辑，最后验证测试覆盖情况，形成评审意见；评审意见分为“必须修改（Blocking）”和“建议修改（Non-blocking）”，必须修改的问题需明确指出，建议修改的问题可提供优化方向。反馈规范：评审意见需客观、专业、友好，避免使用攻击性语言（如“这代码太烂了”“重写吧”），建议使用建设性语言，如“这个方法的圈复杂度达到了12，建议拆分为几个更小的方法，可将验证逻辑和业务处理分离”；评审意见需标记具体代码行，明确问题所在和修改建议。提交者需在24小时内响应评审意见，对每条意见明确回复（已修改、暂不修改及理由）；修改完成后，重新提交评审，直至评审通过；若评审过程中出现技术争议，提交技术负责人裁决。3.3.4特殊场景处理紧急修复：简化评审流程，但不跳过评审，事后补充完整评审记录，标记为需后续复查；新手代码审查：增加设计模式、规范细节的指导，提供学习资源链接，平衡严格度与鼓励，帮助新手快速适应规范；架构重大变更：安排专项设计评审，使用架构决策记录（ADR），邀请架构师、多模块负责人参与评审，确保架构合理性。3.4代码维护规范3.4.1日常维护定期重构代码，消除技术债务，如将过时的硬编码常量移至配置文件、拆分过长方法、优化耦合代码；及时修复线上bug，修复后需同步更新测试用例，避免同类bug重复出现；定期清理无用代码、注释、配置，保持代码整洁。代码维护过程中，需遵循“最小修改原则”，仅修改必要的代码，避免因修改引发新的问题；修改代码后，必须进行测试，确保功能正常。3.4.2版本管理每个版本发布前，需对代码进行全面评审和测试，确保代码质量；版本号遵循语义化版本规范（Major.Minor.Patch），如1.0.0，Major为重大版本（不兼容变更），Minor为次要版本（新增功能，兼容旧版本），Patch为补丁版本（修复bug，兼容旧版本）。版本发布后，需留存版本备份，记录版本变更日志（包括新增功能、修复的bug、优化内容、不兼容变更），便于后续追溯和回滚。3.4.3文档同步代码修改后，需同步更新相关文档（如接口文档、技术设计文档、用户手册），确保文档与代码一致；新增功能、修改核心逻辑后，需补充或更新注释，便于后续维护人员理解。第四章主流编程语言专项规范4.1Java语言规范遵循GoogleJavaStyleGuide，补充以下专项要求：包命名：采用全小写字母，以公司域名反转开头，按模块划分，如ject.controller、ject.service；异常处理：禁止使用e.printStackTrace()，需使用日志框架（如Logback、Log4j）记录异常信息；集合使用：优先使用泛型集合（如List<String>），禁止使用非泛型集合；避免使用ArrayList、HashMap的无参构造函数（初始化容量不足时会频繁扩容），根据预估容量指定初始值；注解使用：Override、Deprecated、SuppressWarnings等注解需正确使用，Override用于重写父类方法，Deprecated用于标记废弃方法并说明替代方案；工具类：工具类需定义为抽象类或私有构造函数，禁止实例化，如publicabstractclassStringUtils{}；静态分析工具：使用Checkstyle、PMD进行代码检查，修复所有严重、高危问题。4.2Python语言规范遵循PEP8规范，补充以下专项要求：缩进：统一使用4个空格，禁止使用制表符；行长度：单条代码行长度不超过79个字符，注释行不超过72个字符；导入规范：导入顺序为标准库→第三方库→自定义库，不同类型导入之间加1个空行；禁止使用fromxxximport*（除非是测试场景）；函数与类：函数、类之间加2个空行；类的方法之间加1个空行；变量命名：采用下划线命名法（snake_case），如user_name、calculate_average；静态分析工具：使用autopep8、flake8进行代码检查，配合pre-commit钩子实现提交前强制检查。4.3JavaScript/TypeScript语言规范遵循AirbnbJSStyleGuide，补充以下专项要求：变量声明：优先使用const、let，禁止使用var；const用于声明不可变变量，let用于声明可变变量；箭头函数：优先使用箭头函数（()=>{}），简化回调函数写法，避免this指向问题；对象与数组：对象字面量优先使用简洁语法（如{name,age}代替{name:name,age:age}）；数组使用字面量（[]）代替newArray()；Promise：异步操作优先使用async/await，避免嵌套Promise；类型定义：TypeScript需明确类型定义，禁止使用any类型（除非有特殊场景）；静态分析工具：使用ESLint、Prettier进行代码检查和格式化，统一代码风格。4.4Go语言规范遵循UberGoStyleGuide，补充以下专项要求：命名规范：包名采用全小写，简洁且与功能相关（如utils、model）；函数、变量采用小驼峰命名法，常量采用全大写下划线分隔；错误处理：禁止忽略错误（如_=err），需对错误进行处理或返回；自定义错误需包含详细信息，使用errors.New或fmt.Errorf；代码格式：使用gofmt、golint工具自动格式化代码，确保格式一致；函数：函数参数不超过3个，超过3个需使用结构体封装；函数返回值尽量简洁，避免返回过多值；并发：使用goroutine时需注意线程安全，合理使用sync包进行同步；禁止使用panic（除非是程序无法恢复的错误）。第五章工具使用规范5.1代码编辑工具团队统一使用指定的代码编辑工具（如IntelliJIDEA、VSCode、PyCharm），安装统一的插件（如ESLint、Prettier、Checkstyle），配置统一的代码格式化规则（如缩进、行长度、空格），确保编辑工具生成的代码符合本手册规范。禁止使用记事本、写字板等无语法高亮、无格式化功能的工具编写代码；编辑工具的自动保存、自动格式化功能需开启，减少手动格式化成本。5.2静态分析工具各语言对应的静态分析工具必须强制使用，确保代码符合规范、无基础缺陷，具体工具如下：编程语言推荐工具核心功能JavaSonarQube、Checkstyle、PMD规范检查、缺陷扫描、性能分析、安全漏洞检测Pythonautopep8、flake8、pylintPEP8规范检查、语法错误检测、代码质量评分JavaScript/TypeScriptESLint、Prettier代码规范检查、自动格式化、语法错误检测Gogofmt、golint、govet代码格式化、规范检查、语法错误检测静态分析工具的检查结果需及时处理，严重、高危问题必须修复