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

软件开发工程师代码规范工作手册第一章总则1.1目的为统一团队编码标准，提高代码的可读性、可维护性、可复用性和安全性，降低团队协作成本，减少潜在缺陷，保障项目交付质量与长期迭代效率，特制定本手册。本手册适用于团队所有软件开发工程师（含前端、后端、移动端）在各类项目开发过程中的编码活动，是代码编写、评审、优化的核心依据。1.2适用范围本手册适用于团队所有在研、新建的软件项目，涵盖需求开发、迭代优化、bug修复、重构等所有涉及代码编写的场景；适用于团队所有软件开发工程师，包括正式员工、实习生及外包开发人员，所有人员必须严格遵守本手册规范，特殊场景需经技术负责人审批后方可偏离。1.3核心原则可读性优先：代码不仅是给机器执行，更是给人阅读，确保他人能快速理解代码逻辑、功能用途及设计思路；一致性原则：同一项目、同一模块的编码风格、命名规则、注释规范保持统一，避免出现“一人一风格”；安全性原则：编码过程中需规避常见安全隐患（如SQL注入、XSS攻击、空指针异常等），优先使用安全合规的编码方式；可维护性原则：代码结构清晰、模块化拆分合理，便于后续迭代、bug修复及功能扩展，减少“牵一发而动全身”的情况；高效性原则：在保证代码质量的前提下，兼顾代码执行效率，避免冗余代码、无效计算及不合理的资源占用。1.4责任与监督1.软件开发工程师：严格按照本手册规范编写代码，主动进行自我检查，确保提交的代码符合规范；2.代码评审人：在代码评审过程中，重点检查代码是否符合本手册规范，对不符合规范的代码提出整改意见，未整改合格不得通过评审；3.技术负责人：负责本手册的更新、维护与推广，监督规范的执行情况，协调解决规范执行过程中的争议问题；4.团队全员：有权对不符合规范的代码提出异议，共同维护编码规范的严肃性，推动团队编码质量提升。第二章通用编码规范2.1命名规范2.1.1通用命名原则1.语义化命名：命名需准确反映变量、函数、类、接口等的功能或用途，避免使用无意义的缩写（如a、b、temp等），特殊领域的通用缩写除外（如ID、URL、JSON等）；2.大小写规范：严格区分大小写，不同类型的命名采用对应的大小写格式，禁止混用；3.长度适中：命名长度控制在3-20个字符之间，过长易冗余，过短无法体现语义；4.禁止使用关键字：不得使用编程语言的保留关键字（如Java中的class、int，JavaScript中的let、const等）作为命名，也不得使用与框架、库冲突的名称。2.1.2变量命名1.采用小驼峰命名法（camelCase）：首字母小写，后续每个单词首字母大写，如userName、orderId、totalAmount；2.布尔类型变量：命名需体现“是否”含义，优先使用is、has、can、should开头，如isLogin、hasPermission、canEdit；3.常量命名：采用全大写+下划线分隔（UPPER_SNAKE_CASE），如MAX_PAGE_SIZE、USER_ROLE_ADMIN、DEFAULT_TIMEOUT；4.数组/集合变量：命名需体现集合特性，可使用复数形式或加list、array、map等后缀，如userList、productArray、orderMap。2.1.3函数/方法命名1.采用小驼峰命名法（camelCase），首字母小写，后续每个单词首字母大写；2.动词开头，明确表达函数的核心操作，如getUserInfo（获取用户信息）、saveOrder（保存订单）、deleteById（根据ID删除）；3.避免歧义：函数命名需精准，避免同一功能的不同命名（如get和find区分明确，get用于获取已存在的数据，find用于查询符合条件的数据）；4.参数相关：函数参数命名遵循变量命名规范，参数个数不宜过多（建议不超过5个），过多时可封装为对象。2.1.4类/接口命名1.类命名：采用大驼峰命名法（PascalCase），首字母大写，后续每个单词首字母大写，如UserController、OrderService、ProductEntity；2.接口命名：采用大驼峰命名法，可加I前缀（如IUserService），或直接使用功能名称（如UserRepository），统一项目内命名风格；3.抽象类命名：可加Abstract前缀（如AbstractBaseService），明确抽象类属性；4.异常类命名：以Exception结尾，如BusinessException、ParamException，明确异常类型。2.1.5包/模块命名1.采用全小写，以域名反转作为前缀（如ject），后续按功能模块拆分，如ject.controller（控制层）、ject.service（服务层）；2.模块命名简洁明了，避免多层嵌套（建议嵌套不超过4层），如ject.user.controller（用户控制层）；3.禁止使用中文、特殊字符作为包/模块名称，避免出现空格、下划线（除特殊框架要求外）。2.2代码格式规范2.2.1缩进与换行1.缩进：统一使用4个空格缩进（禁止使用Tab键），确保不同编辑器打开时格式一致；2.换行：每个独立的代码块（如if、for、while循环，类、函数定义）后需换行，逻辑相关的代码放在同一行或相邻行，避免过长行；3.行长度：单行长不超过120个字符，超过时需换行，换行优先在运算符、逗号后，确保换行后代码可读性，如：正确：StringuserInfo=userName+","+userAge+","+userAddress+","+userPhone;错误：StringuserInfo=userName+","+userAge+","+userAddress+","+userPhone+","+userEmail+","+userRole;4.空行：类内部，不同方法之间需空1行；方法内部，不同逻辑块之间可空1行（避免过多空行）；包导入与类定义之间空1行，注释与代码之间可空1行。2.2.2括号与运算符1.括号：采用“左括号紧跟，右括号换行”的风格，如：正确：if(isLogin){

returnuserInfo;

}错误：if(isLogin)

{

returnuserInfo;

}2.运算符：算术运算符（+、-、*、/）、逻辑运算符（&&、||）、比较运算符（==、!=、>、<）前后各加1个空格，如：正确：intsum=a+b;booleanisEqual=(a==b)&&(c!=d);错误：intsum=a+b;booleanisEqual=(a==b)&&(c!=d);3.赋值运算符（=、+=、-=等）前后各加1个空格，逗号（,）后加1个空格，分号（;）后加1个空格（行尾分号除外）。2.2.3注释规范注释的核心目的是解释“为什么这么写”，而非“写了什么”，避免冗余注释，确保注释与代码同步更新（代码修改后，对应注释需及时修改）。1.类注释：位于类定义上方，使用文档注释（如Java的/***/），包含类的功能描述、作者、创建日期、修改记录等，如：/**

*用户控制层，负责处理用户相关的HTTP请求

*@author软件开发工程师

*@date2026-03-22

*@version1.0

*/2.方法注释：位于方法定义上方，使用文档注释，包含方法功能、参数说明、返回值说明、异常说明等，如：/**

*根据用户ID获取用户详细信息

*@paramuserId用户ID（非空，长度为10-20位）

*@returnUserInfo用户详细信息（null表示无此用户）

*@throwsBusinessException当userId为空或格式错误时抛出

*/3.行注释：使用//注释，用于解释单行代码的特殊逻辑、临时说明，避免对显而易见的代码进行注释（如//定义变量a，无需注释）；4.块注释：使用/**/注释，用于注释多行代码（如临时注释掉的代码块），但不建议长期保留注释掉的代码，无用代码需及时删除；5.特殊注释：需标注TODO（待完成）、FIXME（需修复）、NOTE（注意事项）等，便于后续跟踪，如：//TODO完善参数校验逻辑。2.3代码冗余与优化规范1.禁止冗余代码：避免重复编写相同逻辑的代码，可封装为函数、工具类进行复用；无用的变量、函数、注释需及时删除，不保留“僵尸代码”；2.避免过度封装：封装需结合实际需求，避免为了封装而封装，导致代码复杂度提升；3.简化逻辑：复杂逻辑需拆分为多个小函数，每个函数只负责一个功能（单一职责原则）；避免嵌套过深（建议嵌套不超过3层），可通过提前return、使用elseif等方式简化；4.资源释放：对于文件流、数据库连接、网络连接等资源，需确保及时释放，优先使用try-with-resources（Java）、using（C#）等自动释放机制，避免资源泄露；5.避免魔法值：代码中禁止出现无意义的魔法值（如数字、字符串），需定义为常量，如：正确：if(status==ORDER_STATUS_PAID){...}（ORDER_STATUS_PAID为常量，值为1）错误：if(status==1){...}（无法明确1代表的含义）。第三章分语言编码规范3.1Java编码规范3.1.1基础规范类的访问修饰符：明确类的访问范围，优先使用private（私有）、protected（受保护），避免随意使用public（公共）；成员变量：优先使用private，通过getter/setter方法访问，避免直接暴露成员变量；静态成员变量需加static关键字，常量需加final关键字；方法返回值：避免返回null（除非必要），可返回空集合、Optional对象等，减少空指针异常；异常处理：避免捕获所有异常（catch(Exceptione)），需精准捕获特定异常；异常处理需有具体逻辑（如日志记录），禁止空catch块；集合使用：优先使用泛型（如List<User>），避免使用原始类型；根据需求选择合适的集合（如查询频繁用HashMap，有序用LinkedHashMap）；代码风格：遵循阿里巴巴Java开发手册，禁止使用ArrayList的subList方法（易引发ConcurrentModificationException），避免使用System.out.println（需用日志框架替代）。3.1.2命名补充1.接口实现类：以Impl为后缀，如UserServiceImpl（实现IUserService接口）；2.实体类：对应数据库表，命名与表名一致（驼峰转下划线），如UserEntity对应user表，OrderItemEntity对应order_item表；3.工具类：以Util为后缀，如DateUtil、StringUtil，工具类方法优先使用静态方法，禁止实例化。3.2JavaScript/TypeScript编码规范3.2.1基础规范变量声明：优先使用const（常量）、let（变量），禁止使用var（避免变量提升导致的问题）；箭头函数：简洁逻辑优先使用箭头函数，避免this指向混乱；复杂逻辑可使用普通函数；对象与数组：对象字面量优先使用简洁语法，如constuser={userName,userAge}（替代{userName:userName,userAge:userAge}）；数组使用字面量创建（如constlist=[]），避免使用newArray()；异步处理：优先使用async/await（简洁易读），避免过多嵌套的Promise.then()；类型定义：TypeScript需明确变量、函数的类型，避免使用any类型（除非特殊场景）；避免全局污染：禁止在全局作用域定义变量、函数，可使用模块（import/export）封装。3.2.2命名补充1.组件命名（前端框架）：采用大驼峰命名法，如UserList、LoginForm，与文件名保持一致；2.事件处理函数：以on开头，如onClick、onSubmit、onUserChange；3.钩子函数：遵循框架规范，如React的useEffect、useState，Vue的created、mounted，不随意修改钩子函数命名。3.3其他语言补充规范1.Python：采用PEP8规范，变量、函数命名使用下划线分隔（snake_case），类命名使用大驼峰，缩进使用4个空格，导入包按“标准库→第三方库→自定义库”的顺序，之间空1行；2.Go：变量、函数命名使用小驼峰，包名全小写且简洁，函数参数、返回值命名清晰，避免使用全局变量，遵循Go官方编码规范；3.移动端（Android/iOS）：Android遵循Java/Kotlin规范，Kotlin命名与Java一致；iOS遵循Swift/OC规范，Swift类、结构体使用大驼峰，变量、函数使用小驼峰，OC类以大写字母开头（如NSString）。第四章版本控制规范4.1分支管理规范1.主分支（main/master）：用于存放正式发布的代码，禁止直接在主分支上编写、提交代码；2.开发分支（develop）：用于团队日常开发，所有功能开发、迭代优化均基于develop分支创建子分支；3.功能分支（feature/*）：基于develop分支创建，用于开发单个功能，命名格式为feature/功能名称（如feature/user-login、feature/order-pay），功能开发完成后，提交合并请求（MR/PR）到develop分支，评审通过后合并；4.修复分支（bugfix/*）：基于develop分支创建，用于修复开发过程中的bug，命名格式为bugfix/bug描述（如bugfix/user-login-fail），修复完成后合并到develop分支；5.发布分支（release/*）：基于develop分支创建，用于版本发布准备，命名格式为release/版本号（如release/1.0.0），发布完成后合并到main分支和develop分支；6.紧急修复分支（hotfix/*）：基于main分支创建，用于修复线上紧急bug，命名格式为hotfix/版本号-bug描述（如hotfix/1.0.1-login-error），修复完成后合并到main分支和develop分支。4.2提交规范1.提交信息格式：统一采用“类型:描述”的格式，类型小写，描述简洁明了（不超过50字），如：feat:新增用户登录功能

fix:修复订单支付失败bug

docs:更新代码规范手册

style:调整代码格式（不修改逻辑）

refactor:重构用户模块代码（不新增功能、不修复bug）

test:新增单元测试

chore:优化构建脚本、依赖更新等2.提交频率：每个小功能、每个bug修复完成后及时提交，避免一次性提交大量代码（建议单次提交代码行数不超过500行）；3.提交内容：只提交与当前功能、bug修复相关的代码，禁止提交无关文件（如IDE配置文件、日志文件、临时文件等），可通过.gitignore文件过滤无关文件；4.提交前检查：提交前需自行检查代码是否符合本手册规范，是否存在语法错误、冗余代码，确保代码可运行。4.3合并请求（MR/PR）规范1.合并请求标题：与提交信息格式一致，明确合并的内容（如“feat:新增用户登录功能，合并到develop分支”）；2.合并请求描述：详细说明合并的功能、修改的内容、测试情况，如有相关文档需同步更新；3.评审要求：每个合并请求需至少1名代码评审人审核，评审通过后才能合并；评审过程中需针对代码规范、逻辑合理性、安全性提出意见，整改完成后重新评审；4.冲突处理：合并前需解决分支冲突，冲突解决后需重新测试，确保代码正常运行。第五章安全编码规范5.1通用安全规范输入校验：所有用户输入（如表单提交、URL参数、接口参数）必须进行校验，包括格式、长度、范围等，避免恶意输入；输出编码：返回给前端的内容需进行编码（如HTML编码、URL编码），避免XSS攻击；敏感数据保护：密码、身份证号、手机号等敏感数据需加密存储（如密码使用MD5、SHA256等加密算法），禁止明文存储；传输过程中需使用HTTPS协议；权限控制：接口、页面需进行权限校验，确保用户只能访问自己有权限的资源，避免越权访问；避免SQL注入：使用参数化查询（如PreparedStatement、MyBatis的#{}），禁止拼接SQL语句；日志安全：日志中禁止打印敏感数据（如密码、token），避免泄露用户信息；依赖安全：定期更新项目依赖，避免使用存在安全漏洞的依赖包（可通过依赖检测工具排查）。5.2分场景安全规范1.前端安全：禁止在本地存储敏感数据（如localStorage存储密码）；避免使用eval()、innerHTML等易引发XSS攻击的方法；2.后端安全：接口需进行token校验、签名校验，防止接口被恶意调用；限制接口请求频率，避免恶意刷接口；3.数据库安全：数据库账号权限最小化，禁止使用root账号连接应用；定期备份数据库，防止数据丢失；4.移动端安全：避免存储敏感数据到本地文件；校验APP的签名，防止APP被篡改；禁止明文传输敏感数据。第六章代码评审规范