程序代码规范手册

程序代码规范手册前言在软件开发的全流程中，代码不仅是机器可执行的指令，更是团队成员间沟通的桥梁、项目知识沉淀的核心载体。一套统一、明确、可落地的代码规范，并非束缚开发者创造力的枷锁，而是减少无效争论、提升协作效率、降低维护成本、预防潜在缺陷的关键工具，更是保障项目长期稳定迭代、提升代码质量的基石。本手册旨在为项目团队建立统一的“代码语言”，明确编码过程中的通用原则、具体标准和实操要求，确保所有开发人员编写的代码具备良好的可读性、可维护性、可复用性和安全性。本手册适用于项目组所有成员，涵盖日常开发中编写的各类代码，包括但不限于源代码、测试代码、配置脚本等，团队成员应共同学习、理解并自觉遵守，将规范执行融入日常开发，视为职业素养的重要组成部分。本手册将根据项目技术栈迭代、团队协作需求变化，定期评审优化，确保规范的适用性和前瞻性。若手册未明确规定的场景，需参考项目中已有的、被广泛接受的代码风格，或经团队核心成员讨论后确定统一标准。第一章通用编码原则所有编码行为需遵循以下核心原则，这些原则贯穿编码全流程，是制定具体规范的基础，优先于任何细节规则。1.1清晰优先，效率为辅除非有明确的性能瓶颈并已通过profiling确认，否则代码的可读性和可理解性应优先于极致的性能优化。晦涩难懂的“聪明”代码往往会成为后续维护的隐患，编写代码时需兼顾执行效率与人类可读性，让后续阅读者（包括未来的自己）能快速理解代码意图。1.2简洁为王，拒绝冗余追求代码的简洁性，去除不必要的复杂性和重复代码，遵循“少即是多”的原则。重复代码不仅会增加维护成本，还会提升缺陷出现的概率，对于重复逻辑应提炼为通用函数、工具类或模块，实现代码复用。1.3一致性至上在项目范围内保持代码风格、命名规则、格式规范的统一。遵循本手册的明确规定，若手册未覆盖，需参考项目现有代码的主流风格，避免因个人习惯导致代码风格混乱，减少团队成员的认知成本。1.4面向维护，兼顾未来编写代码时需时刻考虑后续维护场景，代码结构清晰、逻辑连贯，注释完整且同步更新。同时预留合理的扩展空间，避免因需求迭代导致大规模代码重构，兼顾代码的灵活性和稳定性。1.5异常可控，拒绝静默明确处理各种可能的异常情况，包括输入非法、资源不足、依赖异常等，提供有意义的错误信息，便于问题定位和排查。禁止程序静默失败，确保任何异常都能被捕捉、记录并合理处理。1.6单一职责，分工清晰函数、类、模块应专注于完成单一职责，避免“大而全”的设计。单一职责的代码更易于理解、测试、复用和修改，当一个函数或类的职责超过一个时，应进行拆分。第二章命名规范命名是代码可读性的第一道关卡，一个好的命名能够清晰表达其含义、用途和行为，几乎无需额外注释。所有命名需遵循“见名知意、规范统一、避免模糊”的核心要求，严格遵循对应编程语言的约定俗成。2.1通用命名要求含义明确，避免模糊：命名应准确描述其代表的实体、功能或行为，禁止使用data、info、process、handle等含义宽泛的词语。例如，calculateTotalPrice()优于processData()，userName优于name。统一使用英文：代码是国际协作的工具，所有命名必须使用英文，禁止使用拼音、中文或其他语言，避免出现拼音与英文混用的情况（如userMingzi❌）。避免冗余缩写：仅允许使用行业内广为人知的缩写（如max、min、avg、id、URL、API），禁止使用不通用的缩写（如usr代替user、pwd代替password❌）。区分有意义：禁止仅通过大小写区分相似的命名（如User和user、Order和order❌），此类命名极易混淆，易导致编码错误。不使用关键字：禁止使用对应编程语言的关键字、保留字作为命名（如Java中的class、Python中的def、JavaScript中的let），若需使用，可在关键字后添加合理后缀（如classInfo）。2.2具体命名规则命名对象命名规则示例禁止示例变量名小驼峰命名法（camelCase），名词或名词短语，体现变量所代表的实体orderId、customerName、productListorder_id、customername、x❌函数/方法名小驼峰命名法（camelCase），动词或动词短语，体现函数的行为和功能getUserInfo()、saveOrder()、isValidEmail()、calculateTotal()userInfo()、save()、check()❌常量名全大写字母，单词间用下划线分隔（UPPER_SNAKE_CASE），明确标注用途MAX_RETRY_COUNT、DEFAULT_TIMEOUT、PImaxRetryCount、DefaultTimeout、pi❌类名/接口名大驼峰命名法（PascalCase），名词或名词短语，接口可加“I”前缀（可选，按项目约定）CustomerAccount、OrderProcessor、IUserRepositorycustomerAccount、order_processor、IuserRepository❌包名/模块名全小写字母，单词间用小数点（包）或下划线（模块）分隔，按功能/业务领域划分com.example.user.service（Java包）、user_manage（Python模块）Com.Example.User.Service、UserManage❌枚举名大驼峰命名法，枚举值全大写+下划线分隔OrderStatus、ORDER_PAID、ORDER_CANCELLEDorderStatus、OrderPaid❌第三章注释规范注释的核心目的是解释“为什么这么做”以及“难以从代码本身推断的复杂逻辑”，好的代码本身就是一种注释，不应依赖注释来弥补糟糕的命名或混乱的逻辑。注释需遵循“必要、简洁、同步、规范”的原则，避免冗余和过时。3.1注释通用要求必要时才注释：禁止为显而易见的代码添加注释，例如i++旁边写//incrementi（递增i）、inta=10旁边写//定义变量a并赋值10，此类冗余注释会增加维护成本。保持同步更新：注释必须与代码同步修改，过时的注释比没有注释更糟糕，会严重误导阅读者和维护者。若代码逻辑变更，需立即更新对应注释。清晰简洁：用简洁明了的中文（或项目约定的语言）表达，避免冗长、口水话和专业术语堆砌，确保所有团队成员都能理解。禁止注释掉代码：版本控制系统（如Git）是代码回溯的核心工具，不需要的代码应直接删除，而非注释掉保留，避免代码冗余和阅读干扰。统一注释格式：遵循对应编程语言的注释规范（如Java的Javadoc、Python的Docstring），保持注释格式一致，提升可读性。3.2各类注释具体要求3.2.1类/接口注释放在类/接口声明上方，用于说明类/接口的功能、职责、依赖关系、作者、版本等信息，必要时标注创建日期和修改记录。示例（Java）：java

/**

*用户服务类，负责用户信息管理、权限校验、登录认证等核心功能

*依赖：UserDao、TokenService

*@author张三

*@version1.0

*@date2026-03-22

*/

publicclassUserService{

//类内容

}3.2.2函数/方法注释放在函数/方法声明上方，详细说明函数的功能、参数含义、返回值、可能抛出的异常、使用注意事项等，参数和返回值需明确类型和用途。示例（Python）：python

defcheck_user_login(user_id:int,token:str)->bool:

"""

校验用户登录状态

:paramuser_id:用户ID，不能为空，需为正整数

:paramtoken:登录令牌，长度为32位字符串

:return:True=已登录，False=未登录

:raisesTokenExpiredException:令牌过期时抛出

:raisesInvalidTokenException:令牌格式错误时抛出

"""

#核心逻辑：令牌有效期7天，需匹配用户最新登录记录

token_expire_time=7*24*60*60*1000

returnuser_token_dao.check_valid(user_id,token,token_expire_time)3.2.3复杂逻辑注释对于复杂的算法、巧妙的实现、非直观的逻辑或业务规则，需在代码前添加注释，解释其原理、思路或业务背景，帮助阅读者理解代码意图。示例：javascript

//业务规则：订单超时未支付自动取消（超时时间30分钟）

//逻辑说明：先查询未支付订单，过滤出创建时间超过30分钟的订单，批量更新状态为取消

constcancelTimeoutOrders=async()=>{

consttimeout=30*60*1000;//30分钟（毫秒）

constcurrentTime=Date.now();

consttimeoutOrders=awaitorderDao.getUnpaidOrders();

constcancelOrders=timeoutOrders.filter(order=>currentTime-order.createTime>timeout);

awaitorderDao.batchUpdateStatus(cancelOrders,'CANCELLED');

};3.2.4TODO/FIXME注释用于标记需要后续处理的工作，格式统一，需简要说明内容，最好包含负责人或截止日期，便于跟踪和推进。TODO：标记需要完成、优化或补充的代码，示例：//TODO:优化此处查询性能，大数据量下需添加索引（张三，2026-04-10）FIXME：标记已知的bug或问题，需要修复，示例：//FIXME:边界值处理异常，当user_id为0时会报错，需添加校验3.2.5行内注释仅用于解释该行代码的特殊用途或异常逻辑，禁止用于解释常规代码。行内注释需与代码隔开至少2个空格，位于代码右侧。示例：java

intretryCount=3;//最大重试次数，避免频繁请求导致接口限流第四章代码风格与格式规范一致的代码格式能够帮助阅读者快速扫描和理解代码结构，减少因格式差异带来的干扰，提升团队协作效率。所有代码需遵循统一的格式规范，可借助IDE工具（如IDEA、VSCode）的格式化功能自动对齐。4.1缩进规范统一使用空格进行缩进，禁止混合使用空格和制表符（Tab），避免不同编辑器显示差异。缩进空格数统一为4个（Python除外，Python遵循PEP8规范，使用4个空格缩进），续行缩进需与上一行逻辑对齐，增强可读性。示例（Java）：java

//正确

if(orderStatus=="PAID"){

//4个空格缩进

calculateTotalPrice(order);

saveOrderLog(order);

}

//错误（混合Tab和空格）

if(orderStatus=="PAID"){

//Tab缩进，与空格缩进不一致

calculateTotalPrice(order);

saveOrderLog(order);

}4.2行宽限制单行代码长度限制为120个字符，特殊情况（如长字符串、复杂表达式）可放宽至140个字符，超过限制需换行，换行需在合适的位置（如运算符后、逗号后），保持换行后逻辑连贯、对齐整齐。示例：java

//正确（换行对齐）

StringlongMessage="这是一条超长的提示信息，用于说明用户操作失败的原因，"

+"包含具体的错误码和解决建议，便于用户快速排查问题";

//错误（单行超长）

StringlongMessage="这是一条超长的提示信息，用于说明用户操作失败的原因，包含具体的错误码和解决建议，便于用户快速排查问题";

//复杂表达式换行

booleanisValid=(user!=null

&&user.getStatus()=="ACTIVE"

&&StringUtils.isNotBlank(user.getPhone()));

}4.3空格与空行使用4.3.1空格使用运算符（算术运算符、赋值运算符、比较运算符等）两侧各加1个空格，增强可读性。示例：intresult=a+b;if(a==b){}关键字（if、for、while、switch等）与其后的括号之间加1个空格，括号内的表达式与括号之间不加空格。示例：for(inti=0;i<10;i++){}逗号（,）后加1个空格，逗号前不加空格。示例：getUserInfo(userId,userName,phone)函数/方法参数列表中，等号（=）两侧各加1个空格（若有默认值）。示例：defgetUserInfo(user_id,page=1,size=10)禁止多余空格：括号内、括号外、运算符前后不添加多余空格。示例：if(a==b){}❌、intresult=a+b❌4.3.2空行使用逻辑块之间（如函数定义之间、循环体前后、不同功能段落之间）使用1个空行分隔，使代码结构更清晰。类的成员变量与方法之间、方法内部的不同逻辑段之间，使用1个空行分隔。禁止连续多行空行（最多保留1个空行），禁止在代码开头、结尾添加多余空行。示例：java

publicclassOrderService{

//成员变量

privateOrderDaoorderDao;

//空行分隔成员变量与方法

publicOrdergetOrderById(LongorderId){

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

thrownewIllegalArgumentException("订单ID无效");

}

//空行分隔不同逻辑段

Orderorder=orderDao.selectById(orderId);

if(order==null){

thrownewRuntimeException("订单不存在");

}

returnorder;

}

//空行分隔不同方法

publicvoidsaveOrder(Orderorder){

//方法逻辑

}

}4.4括号与换行规范条件语句（if、else、switch）、循环语句（for、while、do-while）、函数/方法体的左大括号（{）与声明语句同行，右大括号（}）单独一行，与左大括号对应的声明语句对齐。单个语句块（如if后只有一行代码），也需添加大括号，避免因缩进错误导致逻辑异常。switch语句中，case、default与switch对齐，case后的代码缩进4个空格，break语句与case代码对齐。示例：java

//正确

if(orderStatus=="PAID"){

saveOrderLog(order);

}elseif(orderStatus=="CANCELLED"){

sendCancelNotice(order);

}else{

updateOrderStatus(order,"PENDING");

}

//错误（左大括号换行）

if(orderStatus=="PAID")

{

saveOrderLog(order);

}

//正确（单个语句块加括号）

if(user==null){

returnfalse;

}

//错误（单个语句块不加括号）

if(user==null)

returnfalse;//后续添加代码易导致逻辑错误4.5导入语句规范导入语句需保持整洁有序，按“标准库→第三方库→项目内部库”的顺序分组，组间使用1个空行分隔。每组内的导入语句按字母顺序排列，禁止导入未使用的包或类，避免冗余。示例（Java）：java

//标准库

importjava.util.List;

importjava.util.Map;

//第三方库

importcom.alibaba.fastjson.JSON;

importorg.springframework.stereotype.Service;

//项目内部库

importcom.example.order.dao.OrderDao;

importcom.example.order.entity.Order;4.6其他格式要求禁止一行多语句：除非语言有特殊简洁写法且不影响可读性，否则一行只写一条语句。示例：inta=10;intb=20;❌，应拆分为两行。字符串拼接：长字符串拼接需换行对齐，避免一行拼接过长，优先使用语言提供的字符串拼接工具（如Java的StringBuilder、Python的f-string）。常量定义：相同类型的常量应集中定义，按功能分组，便于维护和修改。第五章语言特定规范不同编程语言有其独特的特性、语法规则和陷阱，除遵循上述通用规范外，需结合具体编程语言的最佳实践，制定针对性的补充规范。以下为常见编程语言的核心特定规范，团队可根据项目技术栈进一步细化。5.1Java语言规范类的访问修饰符：明确指定类、方法、成员变量的访问修饰符（public、private、protected），禁止使用默认修饰符（包访问权限）。成员变量：私有成员变量（private）需提供getter/setter方法，禁止直接暴露；静态成员变量需加static关键字，命名遵循常量规范（全大写）。异常处理：捕获具体异常，禁止使用catch(Exceptione)捕获所有异常；异常处理需添加日志记录，便于问题定位；避免吞掉异常（即catch块中不做任何处理）。集合使用：优先使用泛型集合（如List<String>），避免使用原始类型；集合初始化时指定初始容量（如newArrayList<>(10)），提升性能。避免空指针：使用StringUtils.isEmpty()、Objects.nonNull()等工具类判断空值，避免直接使用==null判断；禁止返回null的集合，可返回空集合（如Collections.emptyList()）。5.2Python语言规范遵循PEP8规范：缩进使用4个空格，单行代码长度不超过79个字符，函数/类之间空2行，方法之间空1行。命名规范：模块名、包名全小写，单词间用下划线分隔；函数名、变量名用小驼峰或下划线分隔（项目统一即可）；类名用大驼峰。缩进严格：Python依赖缩进来区分代码块，禁止混合空格和Tab，避免因缩进错误导致语法异常。避免可变默认参数：禁止使用列表、字典等可变对象作为函数默认参数（如deffunc(a=[])），易导致意外的副作用。导入规范：禁止使用frommoduleimport*，避免命名冲突；导入语句放在文件顶部，位于注释之后、代码之前。5.3JavaScript/TypeScript语言规范变量声明：优先使用const、let声明变量，禁止使用var（避免变量提升导致的问题）；const用于声明不可变变量，let用于声明可变变量。箭头函数：简洁逻辑优先使用箭头函数，避免this指向混乱；复杂逻辑可使用普通函数。对象与数组：对象字面量使用简洁语法，避免冗余；数组初始化优先使用字面量（如constarr=[1,2,3]），禁止使用newArray()。异步处理：优先使用async/await语法，替代回调函数，提升代码可读性；异步操作需处理异常（try/catch）。类型定义：TypeScript需明确指定变量、函数的类型，避免使用any类型，充分利用类型检查功能。5.4通用补充要求深入理解语言特性：充分利用语言的优势特性，避免使用过时或不推荐的语法（如Java的Vector、Python的print语句）。内存管理：对于需要手动管理内存的语言（如C、C++），务必小心处理内存分配与释放，防止内存泄漏。避免语言陷阱：了解语言中的常见陷阱（如JavaScript的闭包、Python的可变默认参数、Java的自动装箱拆箱），提前规避潜在问题。第六章文件组织与项目结构规范良好的文件组织和项目结构是大型项目可维护性的关键，能够帮助团队快速定位文件、理解项目架构，提升协作效率。文件和目录的命名、组织需遵循“按功能/业务划分、单一职责、层次清晰”的原则。6.1目录结构规范项目目录需按功能、业务领域或层次结构（如MVC）组织，避免杂乱无章；核心目录需统一命名，便于团队理解和定位。示例（JavaWeb项目）：plaintext

src/

├──main/

│├──java/

││└──com/

││└──example/

││├──controller///控制器层，处理请求

││├──service///服务层，业务逻辑

││├──dao///数据访问层，操作数据库

││├──entity///实体类，对应数据库表

││├──util///工具类，通用方法

││├──config///配置类，项目配置

││└──exception///异常类，自定义异常

│└──resources///资源文件

│├──application.yml//全局配置

│├──mapper///MyBatis映射文件

│└──static///静态资源（CSS、JS、图片）

└──test///测试代码目录

└──java/

└──com/

└──example/

├──controller///控制器测试

├──service///服务层测试

└──dao///数据访问层测试6.2文件命名与组织要求文件命名：与类名、模块名保持一致，遵循对应命名规范（如Java类文件与类名相同，Python模块文件与模块名相同），禁止使用无意义的文件名（如test1.java、utils2.py）。单一文件单一职责：一个文件仅包含一个类、一个模块或一组相关的工具函数，避免一个文件包含多个不相关的功能，文件大小控制在合理范围（建议不超过1000行）。相关文件集中存放：功能相关的文件放在同一目录下，如控制器类全部放在controller目录，工具类全部放在util目录，便于查找和维护。资源文件分类：静态资源、配置文件、映射文件等按类型分类存放，避免与源代码混放；配置文件按环境（开发、测试、生产）区分，命名规范（如application-dev.yml）。6.3版本控制规范提交信息规范：每次提交需描述清晰、简洁，明确修改内容，采用“类型:描述”的格式，类型包括feat（新增功能）、fix（修复bug）、docs（文档更新）、refactor（代码重构）、style（格式修改）、test（测试相关）。示例：feat:新增订单查询接口；fix:修复用户登录令牌过期异常。提交频率：保持频繁提交，每次提交仅包含一个功能或一个bug的修改，避免一次性提交大量无关代码，便于问题回溯和代码回滚。分支管理：遵循项目分支规范（如master/main为生产分支、develop为开发分支、feature/*为功能分支、bugfix/*为bug修复分支），禁止直接在master/main分支提交代码。冲突处理：提交代码前需先拉取（pull）最新代码，处理冲突后再提交，避免冲突积累；冲突处理需与相关开发人员沟通，确保逻辑正确。第七章代码质量与安全规范代码规范不仅关注风格和格式，更要保障代码质量和安全性，减少潜在缺陷和安全风险，确保项目稳定运行。7.1代码质量要求避免重复代码：遵循DRY（Don'tRepeatYourself）原则，重复逻辑需提炼为通用函数、工具类或模块，减少冗余，便于维护。函数长度控制：单个函数代码长度不超过80行，复杂逻辑需拆分为多个小函数，确保每个函数仅完成单一职责，提升可读性和可测试性。嵌套层级控制：if、for、while等循环/条件语句的嵌套层级不超过3层，超过则拆分函数或调整逻辑，避免代码过于复杂。代码可测试性：编写的代码需便于单元测