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

程序员代码编写规范工作手册（标准版）第1章总则1.1目的为统一团队代码编写标准，提升代码可读性、可维护性、可复用性和安全性，降低开发与维护成本，减少因代码不规范导致的缺陷、冗余及协作冲突，保障项目研发效率与产品质量，特制定本手册。本手册旨在规范程序员编码行为，明确编码标准，使代码达到“统一、清晰、高效、安全”的要求，同时为代码审查、重构、交接提供明确依据，助力团队高效协作与项目长期迭代。1.2适用范围本手册适用于公司所有程序员（含前端、后端、移动端、嵌入式开发），覆盖所有研发项目（新建项目、迭代项目、重构项目）的全部编码环节，包括但不限于：代码编写、注释、命名、格式、结构、错误处理、版本控制、测试调试等。第三方库、框架的使用需符合本规范要求，自定义扩展部分需严格遵循相关章节规定；临时测试代码、调试代码也需遵循基础规范，避免混乱。1.3规范依据本规范基于行业通用标准、主流编程语言官方规范及企业研发实践制定，核心依据包括：Python编码规范（PEP8），作为基础参考，适配Python项目全流程编码；GoogleJavaStyleGuide，指导Java类库及企业级Java项目开发；MicrosoftCStyleGuide，规范C/C++项目编码行为；AirbnbJavaScriptStyle，适配前端JavaScript/TypeScript项目；ISO/IEC12207（软件生命周期过程），强调代码规范在软件开发全流程中的作用；行业内广泛认可的编码惯例（如4空格缩进、命名规范）及公司内部研发实践经验。1.4术语定义为确保团队对规范的理解一致，明确以下核心术语定义：代码风格：指代码的格式化规则，包括缩进、命名、注释、行宽、空行等，直接影响代码可读性；代码审查：通过同行评审发现并修正代码缺陷、规范问题的过程，规范编码可降低审查难度；静态分析：使用工具（如SonarQube、ESLint、Pylint）自动检测代码中的语法、逻辑错误及规范违规；硬编码：在代码中直接嵌入固定值（如密码、API密钥、配置参数），应严格避免，需改为配置文件或常量定义；重构：在不改变代码功能的前提下，优化代码结构、消除冗余、提升可读性，规范编码可降低重构成本；运行时错误：程序执行过程中发生的异常（如空指针引用、数组越界），规范编码可显著减少此类问题；可维护性：代码易于修改、扩展、调试的能力，遵循本规范可显著提升此指标。1.5责任要求1.所有程序员必须严格遵守本手册规定，在编码过程中主动检查代码规范性，确保提交的代码符合标准；2.代码审查人员需以本手册为依据，对代码进行规范审查，对不规范代码提出修改意见，直至符合要求；3.项目负责人需监督团队执行本规范，定期组织规范培训与代码复盘，及时解决规范执行过程中的问题；4.本手册将根据行业技术发展、项目需求变化及团队反馈，定期更新优化，更新后将及时通知所有相关人员。第2章代码格式规范2.1缩进规范缩进是保证代码层级清晰的基础，统一缩进标准可显著提升团队协作效率，具体要求如下：统一使用4个空格作为缩进单位，严禁使用Tab键缩进（不同编辑器的Tab宽度可能不同，会导致代码显示错乱）；Python等对缩进敏感的语言，必须严格遵循4空格缩进，不正确的缩进会导致语法错误；函数、循环、条件判断等代码块内部，每层嵌套需增加4个空格缩进，确保层级清晰可辨；推荐使用IDE的自动缩进功能（如VSCode、IntelliJIDEA的缩进配置），减少手动缩进带来的错误；JavaScript/TypeScript的ES6模块导入、Vue组件模板等场景，需保持统一缩进，避免代码混乱；缩进需连续一致，严禁出现缩进不统一、空格与Tab混用的情况。2.2行宽限制过长的代码行会降低阅读效率，易导致代码逻辑误读，具体要求如下：通用要求：单行车宽不超过120个字符，特殊场景（如长字符串、复杂表达式）可放宽至150个字符；Python项目遵循PEP8规范，行宽不超过79个字符，注释行不超过72个字符；当代码行超过限制时，需合理换行，换行原则：在运算符、逗号后换行，换行后缩进与上一行相关逻辑对齐；示例1（Python长条件）：示例2（JavaScript长JSX表达式）：Go语言的长switch语句、SQL查询语句，需合理换行，确保逻辑清晰。2.3代码行分隔合理的代码行分隔可提升代码结构清晰度，避免逻辑块混淆，具体要求如下：类成员、函数/方法之间，需空1行分隔，保持方法间的视觉独立性；同一个函数/方法内部，不同逻辑块（如参数定义、核心逻辑、返回处理）之间，空1行分隔；TypeScript接口定义、Java类属性定义中，属性过多时，每个属性后可空1行；SQL查询语句中，JOIN条件与主查询、WHERE子句与SELECT子句之间，需空1行分隔；JavaSpringBoot配置类中，@Bean注解的方法需单独成行，并空1行间隔；C/C++的switch语句中，每个case分支需空1行分隔，使用fallthrough时需明确标注；严禁出现连续2行及以上空行，也严禁无空行导致逻辑块混淆的情况。2.4空格使用规范空格的合理使用可提升代码可读性，避免符号拥挤导致的误读，具体要求如下：运算符（+、-、*、/、=、==、!=、>、<等）两侧，各加1个空格；逗号（,）、分号（;）后加1个空格，逗号前不加空格；括号使用：函数名、关键字（if、for、while等）与左括号（(）之间不加空格，左括号与内容之间加1个空格，右括号（)）与内容之间不加空格；示例：花括号（{、}）使用：左花括号（{）紧跟语句末尾，与语句之间加1个空格；右花括号（}）单独成行，与对应语句对齐；数组、集合的中括号（[、]）与内容之间不加空格，如arr[0]、list[1]；对象的点号（.）前后不加空格，如user.getName()、obj.id；严禁多余空格（如行首、行尾、括号内多余空格），避免代码杂乱。2.5注释规范注释是代码的补充说明，规范的注释可显著提升代码可维护性，避免“代码写了没人懂”的问题，注释需遵循“简洁、准确、必要”的原则，具体要求如下：2.5.1注释类型及格式单行注释：使用//，注释内容与//之间加1个空格，适用于简单说明、局部逻辑注释；多行注释：使用/*...*/，适用于类、函数、复杂逻辑的详细说明，避免使用//连续注释多行；文档注释：不同语言遵循对应规范，Java使用Javadoc（/**...*/），Python使用docstring（三引号），JavaScript/TypeScript使用JSDoc，用于生成API文档；特殊注释：使用//TODO:标注待实现功能，//FIXME:标注需修复的问题，//NOTE:标注重要说明，注释后需明确具体内容和责任人（可选）。2.5.2注释范围及要求类/接口注释：必须包含类的功能描述、作者、创建日期，复杂类需补充核心逻辑、使用注意事项；函数/方法注释：必须包含功能描述、参数说明（名称、类型、含义、是否可选）、返回值说明（类型、含义）、异常说明（异常类型、触发场景）；示例（Java方法注释）：复杂逻辑注释：对难以理解的逻辑、特殊处理、优化点、兼容处理等进行说明，避免注释显而易见的代码（如“//定义变量i”）；注释语言：统一使用中文，避免英文缩写（如用“获取”而非“get”），专业术语可保留英文；注释维护：代码修改时，需同步修改对应注释，严禁注释与代码不一致；删除无用代码时，同步删除对应注释；严禁保留注释掉的代码（无用代码需直接删除）；注释位置：单行注释可位于代码行上方或右侧（右侧注释需与代码行保持足够间距）；多行注释、文档注释需位于对应代码上方，与代码空1行分隔；Vue、React等前端组件，需对组件功能、props、生命周期钩子进行注释；SQL语句需对复杂查询逻辑、条件说明进行注释。第3章命名规范命名是代码的“标识符”，一致、有意义的命名可减少沟通成本，提升代码自解释性，避免使用无意义、模糊的命名，核心原则：“见名知意、简洁规范、大小写区分”，不同元素命名要求如下：3.1通用命名原则使用具有描述性的名称，准确反映元素的功能、用途或含义，避免使用a、b、temp、x等无意义名称；避免使用拼音（特殊场景除外，如地名、人名），严禁使用拼音与英文混合命名（如userMingzi）；避免使用缩写（常见标准缩写除外，如id、URL、API、JSON、XML），若使用缩写需确保团队统一理解；命名长度适中，避免过长（一般不超过20个字符），也避免过短导致含义模糊；严禁使用关键字、保留字作为命名（如class、int、function、break等）；同一项目中，相同功能的元素命名需保持一致（如获取用户信息统一用getUserInfo，而非getUser、fetchUser）；布尔类型变量/方法，建议使用is、has、can、enable等前缀，明确表示布尔含义（如isActive、hasPermission、canEdit）。3.2不同元素命名规范3.2.1变量命名通用规范：使用小驼峰命名法（camelCase），即首字母小写，后续单词首字母大写；Python、C/C++变量：可使用蛇形命名法（snake_case），即全小写，单词间用下划线分隔（与PEP8、C语言规范一致）；示例：userId、userName、orderList、dataProcessor（小驼峰）；user_id、order_total（蛇形）；避免使用单个字符命名（循环变量除外，如for(inti=0;...)，但建议循环变量含义明确，如for(intorderId=0;...)）；数组、集合变量：建议使用复数形式或加list、array、map等后缀，如users、orderList、userMap；临时变量：若必须使用，需明确含义，如tempOrderId（临时订单ID），避免单纯用temp命名。3.2.2常量命名通用规范：使用全大写蛇形命名法（UPPER_SNAKE_CASE），单词间用下划线分隔；示例：MAX_TIMEOUT、API_KEY、DB_HOST、ORDER_STATUS_PAID、PI；常量需定义在类的顶部或单独的常量文件中，集中管理，避免分散定义；严禁将变量伪装成常量（如使用final、const修饰后，命名仍用小驼峰）；常量含义需明确，避免模糊命名（如避免使用CONST1、CONST2）。3.2.3函数/方法命名通用规范：使用小驼峰命名法（camelCase），采用“动宾结构”，明确表示函数的操作行为；示例：getUserInfo（获取用户信息）、calculateTotalPrice（计算总价）、saveOrder（保存订单）、deleteUser（删除用户）；查询类方法：使用get、find、select前缀，如getUserById、findOrderByUserId；新增/保存类方法：使用save、add、insert前缀，如saveUser、addOrder；删除类方法：使用delete、remove前缀，如deleteUser、removeOrder；更新类方法：使用update、modify前缀，如updateUserInfo、modifyOrderStatus；布尔类型方法：使用is、has、can前缀，如isUserActive、hasPermission、canSubmit；方法命名需简洁，避免过长，若功能复杂，可拆分方法后再命名；Python方法遵循PEP8规范，使用蛇形命名法，如calculate_total_price、get_user_info。3.2.4类/接口命名通用规范：使用大驼峰命名法（PascalCase），即首字母大写，后续单词首字母大写，采用名词或名词短语；类命名：反映类的功能或用途，示例：User、OrderService、DatabaseConnection、UserInfo；接口命名：可在名词前加I前缀（Java、C#），或直接使用名词，示例：IUserService、IOrderDao、FetchDataApi；抽象类命名：可加Abstract前缀，示例：AbstractUserService、AbstractOrderHandler；异常类命名：加Exception后缀，示例：UserNotFoundException、OrderException；工具类命名：加Util、Helper后缀，示例：StringUtil、DateHelper、DbUtil；类命名需避免过于笼统（如BaseClass、CommonClass），需明确类的职责范围。3.2.5包/模块/文件命名包命名（Java、Python）：全小写，单词间用点（.）或下划线（_）分隔，遵循“反向域名+项目名+模块名”的规则（Java），示例：ject.service、ject.dao；Python包用下划线分隔，如data_processor；模块命名（JavaScript、TypeScript）：全小写，单词间用横线（-）或下划线（_）分隔，示例：user-service、order-utils；文件命名：遵循对应语言规范，Java文件与类名一致（大驼峰），如User.java；JavaScript/TypeScript文件用小驼峰或横线分隔，如userService.js、order-list.ts；Python文件用蛇形命名，如user_processor.py；CSS文件用横线分隔，如user-style.css；文件命名需与文件内容一致，避免文件名与内容不匹配（如文件名为user.js，内容却是订单相关逻辑）；SQL表名：建议使用复数形式，全小写，单词间用下划线分隔，如users、orders；字段名与变量命名一致，用蛇形命名，如user_id、order_total；配置文件命名：全小写，单词间用横线或下划线分隔，明确用途，如application-dev.yml、perties。3.2.6其他命名枚举命名：使用大驼峰命名法，枚举值使用全大写蛇形命名，示例：enumOrderStatus{ORDER_PAID,ORDER_CANCELLED}；常量池命名：使用大驼峰，加Constant后缀，示例：UserConstant、OrderConstant；前端组件命名（Vue、React）：使用大驼峰或横线分隔，示例：UserInfo.vue、OrderList.jsx、user-detail.vue；路由命名：全小写，单词间用横线分隔，与组件/功能对应，示例：/user/list、/order/detail；私有成员（JavaScript、Java）：可加下划线前缀，示例：_connection（Java）、_userName（JavaScript），明确区分公有与私有成员。第4章代码结构规范代码结构的合理性直接影响代码的可维护性和可扩展性，需遵循“单一职责、模块化、低耦合、高内聚”的原则，明确代码组织逻辑，具体要求如下：4.1类与模块结构单一职责原则：每个类/模块只负责一项核心功能，避免“万能类”“万能模块”（如一个类既处理用户逻辑，又处理订单逻辑）；类的大小控制：单个类的代码行数不超过500行，若超过需拆分（如拆分为多个相关类，或提取工具方法）；类的成员顺序：遵循“常量→静态变量→实例变量→构造方法→公有方法→私有方法→内部类”的顺序，保持结构清晰；模块划分：按功能模块划分（如用户模块、订单模块、支付模块），模块间通过接口交互，减少直接依赖；模块依赖：避免循环依赖（如A模块依赖B模块，B模块又依赖A模块），若出现循环依赖，需重构代码，拆分公共逻辑；Python模块：每个模块功能单一，模块内函数/类按逻辑分组，避免模块内代码杂乱；前端模块（Vue/React）：按组件、路由、工具、API、状态管理划分，组件按功能拆分（如页面组件、公共组件）。4.2函数与方法结构单一职责原则：每个函数/方法只完成一个具体功能，避免“一个函数干所有事”；函数长度控制：单个函数/方法的代码行数不超过50行，复杂逻辑需拆分为多个子函数/方法；参数规范：

参数数量控制：单个函数/方法的参数不超过5个，若超过需封装为对象（如Java的DTO、Python的字典）；参数顺序：必填参数在前，可选参数在后，参数含义明确，避免无意义参数；参数默认值：可选参数需设置合理的默认值，避免传递null作为参数（特殊场景除外）；参数验证：函数/方法开头需对必填参数进行验证（如非空、格式、范围验证），验证失败抛出明确异常；返回值规范：

返回值类型明确，避免返回多种类型（如有时返回String，有时返回Integer）；返回值含义清晰，避免返回null（特殊场景需返回null时，需在注释中明确说明）；复杂返回结果：封装为对象或集合，避免返回零散的多个值；布尔类型返回值：明确表示“是/否”，避免返回模糊的布尔逻辑；函数复杂度控制：避免过多嵌套（嵌套层级不超过3层），若嵌套过深，需拆分函数；避免使用过多条件判断，可使用枚举、策略模式优化；早返回原则：对于条件判断，尽量使用早期返回，避免过多嵌套，示例：避免重复代码（DRY原则）：相同逻辑的代码需提取为公共函数/方法，避免重复编写，减少维护成本；私有方法：仅在当前类/模块内使用，用于封装重复逻辑或复杂逻辑，私有方法命名需体现其功能；构造方法：避免在构造方法中执行复杂逻辑（如数据库操作、网络请求），复杂初始化逻辑需提取为init方法；析构方法（C++、Java）：用于释放资源（如文件流、数据库连接），避免在析构方法中抛出异常。4.3代码块组织条件语句（if-else、switch）：

if-else语句：当else分支逻辑过多时，需拆分函数；多个elseif条件需按逻辑顺序排列（如从小到大、从简单到复杂）；switch语句：case分支需按逻辑顺序排列，每个case分支需加break（除fallthrough场景）；default分支必须存在，用于处理异常情况；避免过长的条件表达式，可将复杂条件提取为布尔变量，提升可读性，示例：booleanisQualified=(age>18)&&(score>60)&&(isActive);if(isQualified){...}循环语句（for、while、do-while）：

循环条件明确，避免无限循环（需设置合理的终止条件）；循环体内逻辑简洁，避免复杂逻辑，复杂逻辑需拆分函数；循环嵌套：嵌套层级不超过3层，超过需拆分循环或提取逻辑；for循环：避免在循环条件中执行耗时操作（如数据库查询、函数调用），可提前计算结果；foreach循环：优先使用foreach（增强for循环）遍历集合，避免使用普通for循环（需索引除外）；代码块顺序：同一函数/方法内，按“参数验证→核心逻辑→结果处理→返回值”的顺序组织代码，逻辑清晰；冗余代码：严禁保留无用代码（如注释掉的代码、未使用的变量/函数），无用代码需及时删除；临时代码：调试、测试用的临时代码，需在提交前删除，严禁提交到版本库；代码复用：重复出现2次及以上的逻辑，需提取为公共函数/方法，提升代码复用性；前端代码块：Vue/React组件按“模板→脚本→样式”的顺序组织，脚本内按“导入→组件定义→数据→生命周期→方法→计算属性”的顺序排列；SQL代码块：复杂查询语句需按“SELECT→FROM→JOIN→WHERE→GROUPBY→HAVING→ORDERBY”的顺序排列，合理换行，提升可读性。第5章变量与常量规范5.1变量规范变量声明：

变量需先声明后使用，严禁未声明直接使用；强类型语言（Java、C#、C++）：明确变量类型，严禁使用Object、Any等万能类型（特殊场景除外）；弱类型语言（JavaScript、Python）：变量命名需体现类型，避免类型混淆（如userName表示字符串，userAge表示数字）；变量声明位置：局部变量声明在使用前，且尽量靠近使用位置；成员变量声明在类的顶部，集中管理；变量初始化：

变量声明时需初始化，避免使用未初始化的变量（可能导致空指针、垃圾值等问题）；引用类型变量（对象、数组、集合）：初始化时避免为null，可初始化为空对象、空数组、空集合（如List<String>list=newArrayList<>();）；基本类型变量：初始化为合理默认值（如int类型默认0，boolean类型默认false，String类型默认""）；变量作用域：

最小作用域原则：变量作用域尽量小，避免全局变量（全局变量易导致数据混乱，需谨慎使用）；局部变量：仅在当前函数/代码块内使用，严禁跨函数/代码块使用；成员变量：仅在当前类内使用，如需外部访问，通过get/set方法，严禁直接访问；静态变量：用于存储全局共享数据（如常量、工具类变量），避免滥用静态变量（易导致内存泄漏）；变量使用：严禁重复定义变量（同一作用域内，变量名不可重复）；避免变量名与关键字、函数名、类名冲突；变量赋值：赋值语句需简洁，避免一行多赋值（如inta=1,b=2;可拆分为两行）；避免使用魔法值（未定义的固定值），魔法值需替换为常量；集合变量：

集合初始化时，尽量指定初始容量（如newArrayList<>(10);），提升性能；集合遍历后，若不再使用，需及时清空（尤其是全局集合），避免内存泄漏；避免使用未初始化的集合（如List<String>list;list.add("a");会导致空指针）；数组变量：

数组初始化时，明确数组长度，避免动态扩容（频繁扩容会影响性能）；避免数组越界访问，遍历数组时需检查索引范围；优先使用集合（如List、Set）替代数组，提升代码灵活性和可读性；5.2常量规范常量定义：

常量需使用final（Java）、const（C++、JavaScript）、readonly（C#）等关键字修饰，确保不可修改；常量需集中定义，可定义在类的顶部、单独的常量类或常量文件中，便于管理和修改；避免分散定义常量（如在多个函数中定义相同的常量），导致修改不便；常量分类：

全局常量：适用于整个项目，如系统配置、状态码、公共参数（如MAX_PAGE_SIZE、SUCCESS_CODE）；局部常量：适用于当前类/模块，仅在当前类/模块内使用，避免全局暴露；常量使用：

严禁直接使用魔法值，所有固定值（如状态码、超时时间、配置参数）必须定义为常量；示例：正确：if(orderStatus==OrderConstant.ORDER_PAID){...}；错误：if(orderStatus==1){...}常量命名需准确反映其含义，避免模糊命名（如避免CONST_1、CONST_2）；常量值需合理，避免定义无意义的常量；常量维护：

常量值修改时，需同步检查所有使用该常量的地方，确保无遗漏；无用常量需及时删除，避免冗余；常量分类管理，按功能分组（如状态码常量、配置常量、业务常量），提升可读性；特殊常量：字符串常量：避免频繁创建相同的字符串常量，可使用常量定义或字符串池；日期常量：日期格式、时间戳等固定值，需定义为常量，避免重复编写；数值常量：如π、最大最小值等，需定义为常量，提升代码可读性；第6章错误处理规范错误处理是保证系统稳定性的关键，需遵循“早发现、早处理、可追溯”的原则，明确错误处理逻辑，避免未捕获异常导致系统崩溃，具体要求如下：6.1错误类型定义按错误级别分类：系统错误（如数据库连接失败、服务器异常）、业务错误（如参数错误、权限不足）、网络错误（如请求超时、连接失败）；按错误来源分类：客户端错误（如前端参数传递错误）、服务端错误（如后端逻辑错误、数据库错误）、第三方错误（如第三方接口调用失败）；自定义异常：针对业务场景，定义自定义异常（如UserNotFoundException、OrderException），异常命名需加Exception后缀，明确异常含义；异常分层：系统异常、业务异常、第三方异常需分层处理，避免混淆，便于定位问题；错误码规范：定义统一的错误码体系，错误码需包含错误级别、模块标识、具体错误编号，示例：SYS_001（系统错误-001）、BUS_002（业务错误-002）；错误码需与错误信息一一对应，集中管理；6.2异常捕获与处理异常捕获原则：

精准捕获：捕获具体异常（如NullPointerException、SQLException），严禁捕获所有异常（如catch(Exceptione)），避免掩盖真正的错误；避免空捕获：严禁catch异常后不做任何处理（如catch(Exceptione){}），至少需记录日志；捕获顺序：先捕获具体异常，后捕获通用异常，避免具体异常被通用异常覆盖；try-catch范围：try块范围尽量小，仅包含可能抛出异常的代码，避免将无关代码放入try块；异常处理逻辑：

异常处理优先级：修复异常→降级处理→提示用户→记录日志；业务异常：捕获后，返回明确的错误信息（错误码+错误描述），提示用户或前端；系统异常：捕获后，记录详细日志，返回通用错误信息（避免暴露系统细节），同时触发告警（可选）；第三方异常：捕获后，记录第三方返回的错误信息，根据业务需求进行重试、降级或提示用户；异常抛出：抛出异常时，需携带明确的错误信息，说明异常原因和触发场景，便于定位问题；避免重复抛出异常：捕获异常后，若无需处理，可直接抛出，避免catch后再throw，增加冗余；finally块使用：用于释放资源（如文件流、数据库连接、网络连接），无论是否抛出异常，finally块都会执行；严禁在finally块中抛出异常，避免覆盖原异常；不同语言异常处理规范：

Java：使用try-catch-finally或try-with-resources（自动关闭资源），自定义异常继承Exception或RuntimeException，根据业务场景选择受检异常或非受检异常；Python：使用try-except-else-finally，捕获具体异常（如ValueError、TypeError），避免捕获BaseException；JavaScript/TypeScript：使用try-catch，或Promise.catch()处理异步异常，自定义异常可使用Error类扩展；C/C++：使用try-catch-throw，异常类型可自定义，抛出异常时需确保异常可被捕获，避免未捕获异常导致程序崩溃；6.3错误日志记录日志记录原则：所有异常、错误都需记录日志，日志需包含“时间、错误级别、模块、错误信息、异常堆栈”，便于定位问题；日志级别规范：按严重程度分为DEBUG（调试）、INFO（信息）、WARN（警告）、ERROR（错误）、FATAL（致命），根据错误级别记录日志；日志内容要求：

ERROR级别：记录系统错误、业务错误，包含错误原因、触发场景、异常堆栈；WARN级别：记录潜在风险（如参数不规范、超时警告），无需异常堆栈，但需说明警告原因；INFO级别：记录正常业务流程（如接口调用成功、用户操作），简洁明了；DEBUG级别：记录调试信息（如变量值、函数调用