程序代码规范手册

程序代码规范手册1.前言1.1目的为统一团队代码编写标准，提升代码可读性、可维护性、可复用性和安全性，减少因编码风格不一致导致的协作成本与潜在缺陷，规范开发流程，保障项目质量与迭代效率，特制定本手册。本手册是团队所有成员在程序开发过程中必须遵循的基本准则，适用于所有项目的代码编写、审查、维护等全流程。1.2适用范围本手册适用于团队所有开发人员（包括前端、后端、测试开发等），覆盖所有编程语言（Java、Python、JavaScript等）、所有项目模块（业务逻辑、工具类、接口开发、测试代码等），涵盖代码编写、注释、提交、审查等各个环节。1.3核心原则本手册所有规范均围绕以下核心原则制定，优先级从高到低依次为：可读性>可维护性>简洁性>性能。除非有明确的性能瓶颈并已通过profiling确认，否则代码的可读性和可理解性应优先于极致的性能优化，晦涩难懂的“聪明”代码往往是未来的隐患。具体原则如下：一致性：团队内统一编码风格，避免个人偏好主导，减少认知成本；清晰性：代码逻辑清晰，命名规范，注释精准，便于他人快速理解；简洁性：避免冗余代码，提炼通用逻辑，拒绝不必要的复杂性；安全性：规避常见安全隐患，如SQL注入、XSS攻击等，保障代码健壮性；可测试性：代码结构清晰，便于编写单元测试，降低测试成本；兼容性：兼顾代码与现有系统、第三方依赖的兼容性，便于后续迭代升级。2.通用编码规范2.1命名规范命名是代码可读性的第一道关卡，核心要求是“见名知意”，避免模糊、缩写（广为人知的缩写如max、min、id除外）、拼音或无意义命名，严格遵循各语言约定俗成的命名风格，区分大小写需有明确意义，避免仅通过大小写区分相似变量（如User和user）。2.1.1通用命名规则统一使用英文命名，禁止使用中文、拼音或拼音缩写（如“yonghuming”“usr”禁止，“userName”“id”允许）；命名长度适中，避免过短（如a、b、c）或过长（建议不超过30个字符），兼顾简洁性与可读性；避免使用Java、Python等语言的关键字、保留字作为命名（如class、int、def、if等）；变量名通常使用名词或名词短语，方法名通常使用动词或动宾短语，常量名需明确标注用途。2.1.2各类型命名细节命名类型命名风格示例（正确）示例（错误）类/接口大驼峰命名法（PascalCase），名词/名词短语；接口可加“I”前缀UserService、IOrderRepository、DatabaseConnectionuserservice、User_service、IuserService方法/函数小驼峰命名法（camelCase），动词/动宾短语getUserById、calculateTotalAmount、checkUserLoginGetUserById、calculate_total、getuser变量/参数小驼峰命名法（camelCase），名词/名词短语userName、orderId、inputDataUserName、order_id、data常量全大写+下划线分隔（SNAKE_CASE）MAX_RETRY_COUNT、API_TIMEOUT、DEFAULT_TIMEOUTmaxRetryCount、MaxRetry、max_retry_count包/模块全小写，单词间用“.”（包）或下划线（模块）分隔com.example.user.service、data_processorCom.Example.User.Service、dataProcessor枚举大驼峰命名法，枚举值全大写+下划线分隔OrderStatus、ORDER_PAID、ORDER_CANCELLEDorderStatus、Order_paid、orderPaid2.2代码格式规范统一的代码格式可降低阅读成本，避免因格式差异导致的理解偏差，所有代码需遵循以下格式要求，优先使用IDE自动格式化工具（如Checkstyle、Prettier、flake8等）保证一致性。2.2.1缩进与换行缩进统一使用空格，禁止使用制表符（Tab），避免不同编辑器显示差异；Java、Python缩进为4个空格，JavaScript缩进为2个空格，严格遵循对应语言的官方规范；代码块（if、for、while、类、方法等）必须缩进，缩进层级清晰，嵌套层级不超过3层，超过则拆分函数或方法；单行代码长度限制为120字符（特殊场景可放宽至140字符），超长时需在适当位置换行，换行优先在运算符、逗号后，保持对齐，避免随意换行；左大括号（{）与声明语句同行，右大括号（}）单独成行，与对应声明语句对齐；Python无大括号，严格遵循缩进规则区分代码块。2.2.2空格与空行运算符（+、-、*、/、=、==、!=、&&等）两侧各加1个空格，增强可读性；逗号（,）、分号（;）后加1个空格，逗号前不加空格；关键字（if、for、while、try、catch等）与括号（(）之间加1个空格，括号内前后不加空格；函数/方法参数列表中，参数之间加1个空格，避免连续空格；逻辑块之间（如函数定义之间、循环体前后、不同功能段落之间）用1个空行分隔，避免连续多行空行（最多不超过2行）；类的成员变量与方法之间、方法内部不同逻辑段之间，用1个空行分隔。2.2.3其他格式要求一行只写一条语句，禁止一行多语句（除非语言有特殊简洁写法且不影响可读性）；导入语句保持整洁有序，按“标准库>第三方库>项目内部库”的顺序分组，组间用1个空行分隔，每组内按字母顺序排列，禁止导入未使用的包或类；避免不必要的括号，但在逻辑不清晰时可添加括号增强可读性（如复杂的条件判断）；字符串拼接优先使用对应语言的推荐方式（如Java用StringBuilder，Python用f-string），避免频繁拼接导致性能问题。2.3注释规范注释的核心目的是解释“为什么这么做”以及“难以从代码本身推断的复杂逻辑”，好的代码本身就是一种注释，避免过度注释、无注释或过时注释。注释需简洁明了、准确无误，与代码同步更新，禁止注释掉的代码（多余代码直接删除，依赖版本控制系统回溯）。2.3.1注释类型及要求类注释：放在类声明上方，使用多行注释，说明类的功能、职责、依赖关系、作者、创建日期等信息，Java使用Javadoc格式，Python使用Docstring格式；方法/函数注释：放在方法声明上方，说明方法功能、参数含义、返回值、异常场景、使用注意事项等，参数和返回值需明确标注类型和意义；代码块注释：用于解释复杂逻辑、算法原理、特殊业务规则，放在代码块上方，简洁说明设计思路，避免描述代码本身（如“//声明变量i”属于无效注释）；单行注释：用于解释局部代码的特殊逻辑，放在代码行上方或右侧（右侧注释与代码之间加2个空格），避免单行注释过长；TODO/FIXME注释：用于标记待完成或需修复的内容，格式为“//TODO:内容（负责人）”“//FIXME:问题描述”，明确责任人或截止时间，便于后续跟踪。2.3.2注释示例Java注释示例java

/**

*用户服务类，负责用户信息的增删改查、权限校验等功能

*@author开发人员姓名

*@date2026-03-25

*@version1.0

*/

publicclassUserService{

/**

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

*@paramuserId用户唯一标识，不能为空

*@return用户信息对象，若不存在则返回null

*@throwsIllegalArgumentException当userId为空时抛出

*/

publicUsergetUserById(LonguserId){

//规则：用户ID需大于0，否则抛出异常（核心逻辑注释）

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

thrownewIllegalArgumentException("用户ID非法");

}

//TODO:后续替换为Redis缓存查询，提升性能（张三）

returnuserDao.selectById(userId);

}

}

Python注释示例python

"""

数据处理模块，负责输入数据的清洗、转换和校验

Author:开发人员姓名

Date:2026-03-25

Version:1.0

"""

defprocess_data(input_data,max_retries=3):

"""处理输入数据并返回结果

Args:

input_data:要处理的数据（字典类型），包含用户基本信息

max_retries:最大重试次数，默认为3，用于处理临时异常

Returns:

dict:处理后的数据，包含清洗后的用户信息和处理状态

Raises:

DataProcessingError:当数据格式非法或处理失败时抛出

"""

#校验数据格式，若格式错误直接抛出异常

ifnotisinstance(input_data,dict):

raiseDataProcessingError("输入数据必须为字典类型")

try:

result=transform_data(input_data)

returnnormalize_result(result)

exceptDataProcessingErrorase:

ifmax_retries>0:

#重试逻辑：每次重试间隔1秒（特殊逻辑注释）

time.sleep(1)

returnprocess_data(input_data,max_retries-1)

raise

3.语言特定编码规范不同编程语言有其独特的特性和陷阱，除遵循上述通用规范外，需严格遵循对应语言的官方规范和社区主流实践，以下为三大主流语言的核心补充规范。3.1Java语言规范遵循GoogleJavaStyleGuide，包名采用“倒置域名+模块名”格式（如ject.service），全小写无下划线；成员变量私有化（private），通过getter/setter方法访问，禁止直接暴露成员变量；异常处理：捕获具体异常（禁止捕获万能的Exception），提供清晰的错误信息，避免吞掉异常，finally块用于清理资源（如关闭流、连接）；避免使用过时API（如Vector、Hashtable），优先使用ArrayList、HashMap等高效集合；并发编程：多线程环境下使用synchronized或ReentrantLock保证线程安全，避免在synchronized块中执行耗时操作，合理使用线程池管理并发任务；日志使用：使用SLF4J等日志框架替代System.out.println，合理设置日志级别（DEBUG、INFO、ERROR），避免生产环境输出过多调试信息。3.2Python语言规范严格遵循PEP8规范，缩进为4个空格，模块和包名采用蛇形命名法（snake_case）；避免使用可变默认参数（如deffunc(a=[])），防止多次调用时参数被复用导致异常；导入规范：禁止使用fromxxximport*，避免命名冲突，导入顺序按“标准库>第三方库>本地库”分组；字符串使用双引号（""）或单引号（''）统一，避免混合使用，多行字符串优先使用三引号（""""""）；函数和类的定义之间空2行，同一类中不同方法之间空1行；避免使用分号结束语句，除非一行多语句（不推荐），合理使用推导式简化代码（如列表推导、字典推导）。3.3JavaScript语言规范遵循AirbnbJavaScriptStyle，缩进为2个空格，变量和函数名采用小驼峰命名法，构造函数和类名采用大驼峰命名法；变量声明：优先使用const（常量）、let（变量），禁止使用var，避免变量提升导致的问题；箭头函数：优先用于匿名函数、回调函数，简化代码，但避免在需要this绑定的场景使用；对象和数组：对象字面量使用简洁语法，避免使用newObject()；数组使用字面量，避免使用newArray()，数组方法优先使用map、filter等高阶函数；异步编程：优先使用async/await，避免回调地狱，异常处理使用try/catch捕获；工具支持：使用ESLint、Prettier自动格式化代码，检查语法错误和规范问题。4.安全编码规范安全编码是保障系统稳定运行的关键，需严格规避常见安全隐患，以下为核心安全规范，所有开发人员必须严格遵守。输入校验：所有用户输入（包括前端传参、接口调用参数）必须进行校验，校验内容包括类型、长度、格式、范围等，防止非法输入；SQL注入防护：使用预编译语句（如Java的PreparedStatement、Python的参数化查询），禁止拼接SQL字符串，避免直接将用户输入代入SQL语句；XSS攻击防护：对用户输入的HTML、JavaScript内容进行转义，禁止直接渲染用户输入的富文本，使用安全的渲染框架；敏感信息保护：禁止硬编码敏感信息（如密码、密钥、数据库连接信息），使用配置文件或安全存储机制（如加密存储），日志中禁止输出敏感信息；权限控制：接口和方法需添加权限校验，确保用户只能访问其权限范围内的资源，避免越权操作；异常处理：避免暴露详细的异常堆栈信息给前端用户，统一返回友好的错误提示，同时记录完整的异常日志便于排查；依赖管理：定期更新第三方依赖，排查依赖中的安全漏洞，禁止使用存在高危漏洞的依赖包。5.代码提交与审查规范5.1代码提交规范代码提交需遵循清晰、规范的提交信息，便于版本回溯和团队协作，提交前需自行检查代码是否符合本手册规范，确保无语法错误、无冗余代码。提交信息格式：【类型】提交描述（简洁明了，不超过50字符），换行后可添加详细说明（可选）；提交类型：feat（新增功能）、fix（修复bug）、docs（文档更新）、style（代码格式调整，不改变逻辑）、refactor（代码重构，不新增功能不修复bug）、test（新增/修改测试代码）、chore（构建/依赖调整）；提交频率：建议每完成一个小功能、修复一个bug或修改一个逻辑块后提交一次，避免大量代码一次性提交；提交前检查：使用IDE格式化工具整理代码格式，检查注释是否完整，删除冗余代码和注释掉的代码，确保代码符合规范。提交示例【feat】新增用户登录接口，支持手机号+验证码登录

详细说明：1.新增loginByPhone方法，实现手机号验证码校验；2.新增验证码发送逻辑，对接短信接口；3.添加接口权限校验。5.2代码审查规范代码审查（CodeReview）是保障代码质量的重要环节，所有代码提交前需经过至少1名团队成员审查，审查通过后方可合并至主分支。审查内容：代码是否符合本手册规范、逻辑是否清晰正确、是否存在安全隐患、注释是否