软件开发编码规范

软件开发编码规范1.总则1.1目的为统一软件开发过程中的编码标准，减少代码冗余、降低维护成本，确保代码的可读性、可复用性、可扩展性和安全性，提升团队协作效率，规避常见编码风险，特制定本规范。本规范适用于所有软件开发相关人员（开发工程师、测试工程师、运维工程师）及所有类型的软件开发项目（前端、后端、移动端等）。1.2核心原则可读性优先：代码被阅读的频率远高于编写频率，优先保证代码易读，避免晦涩难懂的写法，使他人能快速理解代码意图。一致性原则：项目内、模块内、函数内保持编码风格统一，若项目有特定规范，优先遵循项目规范，其次遵循本规范。简洁性原则：避免冗余代码、重复逻辑，用最简洁的代码实现需求，拒绝“过度设计”和“无效代码”，优先复用已有工具类和模块，避免重复造轮子。安全性原则：编码过程中规避常见安全漏洞（如SQL注入、XSS攻击等），敏感数据需加密处理，禁止硬编码敏感信息，守住技术底线。可维护性原则：代码结构清晰、逻辑连贯，便于后续迭代、修改和调试，每个函数、类仅承担单一职责，避免“大函数”“大类”和“嵌套地狱”。1.3适用范围本规范适用于公司所有软件开发项目（包括前端、后端、移动端、嵌入式开发等），所有参与软件开发的人员必须严格遵守，特殊场景（如第三方对接、历史代码兼容）可在团队共识后适当调整，但需留存说明文档。2.通用编码规范2.1命名规范命名核心要求：语义化、简洁化、无歧义，避免使用无意义的缩写（常见标准缩写如id、URL、API除外），禁止使用单个字母（临时迭代变量除外）作为命名，遵循“见名知意”原则，同时区分不同语言的命名习惯。2.1.1变量命名通用规则：小写字母开头，多单词用下划线（snake_case）或小驼峰（camelCase）命名，具体遵循对应语言规范（如Python用snake_case，Java、JavaScript用camelCase），禁止使用拼音命名（特殊业务术语除外，需注释说明）。示例：正确（user_name、userName、age、max_retry_count）；错误（x、a1、yonghu、maxcount）。特殊要求：布尔类型变量命名需体现“是否”含义，优先使用is、has、can等前缀（如is_active、has_permission、can_edit），避免使用模糊命名（如flag、status）。2.1.2常量命名通用规则：全部大写，多单词用下划线分隔（UPPER_SNAKE_CASE），命名需明确常量含义，避免模糊命名。示例：正确（MAX_CONNECTIONS、PI、API_TIMEOUT、MAX_RETRY_ATTEMPTS）；错误（MAX、NUM、TIMEOUT）。特殊要求：常量需集中定义，避免分散在代码中重复定义，禁止在代码中直接使用魔法数字、魔法字符串（如直接写“200”“success”，需定义为常量）。2.1.3函数/方法命名通用规则：动词开头，体现函数核心功能，多单词用下划线或小驼峰命名，遵循对应语言规范，命名简洁且无歧义，避免过长或模糊的函数名。示例：正确（get_user_info、calculate_total_amount、fetch_data、delete_record）；错误（func1、do_something、handle_data）。特殊要求：函数功能单一，一个函数仅完成一个核心任务，函数名需与函数实现完全匹配，避免“名不副实”。2.1.4类/接口命名通用规则：大写字母开头，多单词用大驼峰（PascalCase）命名，体现类/接口的核心职责，避免使用缩写（常见标准缩写除外）。示例：正确（UserProfile、DatabaseConnection、OrderService、UserController）；错误（userprofile、db_conn、order_svc）。特殊要求：接口命名可添加I前缀（如IUserService），抽象类可添加Abstract前缀（如AbstractOrder），异常类需以Error或Exception结尾（如FileNotFoundException）。2.1.5包/模块/文件命名包/模块：全部小写，多单词用下划线分隔（Python）或小写连字符分隔（前端），优先简洁且与功能相关，Python包名不推荐使用下划线，可采用公司域名倒置作为前缀保证唯一性。文件命名：遵循对应语言规范，Python文件用snake_case，前端文件（JS、CSS、Vue）用kebab-case或camelCase，Java文件与类名一致（PascalCase）。示例：正确（data_processor.py、user-service.js、OrderController.java、utils/string_utils.py）；错误（DataProcessor.py、userService.js、ordercontroller.java）。2.2代码格式规范2.2.1缩进统一使用空格缩进，禁止使用制表符（Tab），避免空格与Tab混用导致格式混乱，不同语言缩进空格数遵循对应规范：Python用4个空格，JavaScript用2个空格，Java用4个空格。续行缩进：续行需使用垂直对齐或悬挂缩进，悬挂缩进时可添加额外缩进以区分续行内容与主内容，Python续行可利用括号、方括号、大括号实现隐式行连接，第一行不应有参数时需进一步缩进区分。示例（Python）：正确（函数参数续行）

deflong_function_name(

var_one,var_two,

var_three,var_four

):

print(var_one)

2.2.2行宽与换行每行代码长度控制在80-120个字符，避免超长行，超过限制时需合理换行，换行优先在逗号、运算符后，保证换行后代码逻辑连贯、易读，二元运算符换行可根据可读性选择在换行符之前或之后。禁止一行写多个语句（分号分隔），每个语句单独一行，提升可读性。多行结构的闭合符号（大括号、方括号、圆括号），可与列表最后一行的第一个非空白字符对齐，或与开始多行结构的行的第一个字符对齐。2.2.3空格与空行空格使用：运算符（+、-、*、/、==、!=等）前后各加1个空格；逗号、分号后加1个空格，前面不加空格；函数参数列表中，逗号后加1个空格；括号内侧不加空格（如func(param)，而非func(param)）。空行使用：类与类、函数与函数之间加1-2个空行；函数内部逻辑块之间加1个空行；文件开头（版权注释后）、import语句后、类定义前各加1个空行；注释与被注释代码之间不加空行，注释上方可加1个空行（如需区分逻辑块）。2.2.4大括号与引号大括号：Java、JavaScript等语言采用K&R风格，左大括号紧跟语句末尾，右大括号单独成行，与对应语句对齐；Python无大括号，依靠缩进来区分代码块，严格遵循缩进规则。引号：Python字符串优先使用双引号（""），若字符串内包含双引号则使用单引号（''），文档注释推荐使用三重双引号（"""），不推荐使用三重单引号；JavaScript字符串可根据需求选择单引号或双引号，但项目内需统一。2.3注释规范注释核心要求：简洁、准确、有用，避免冗余注释（如注释与代码完全一致），注释需“与时俱进”，代码修改时同步更新注释，禁止注释掉的代码留存（无用代码直接删除），复杂逻辑必须加注释，简单逻辑可省略注释。2.3.1单行注释使用对应语言的单行注释符号（Python用#，Java、JavaScript用//），注释内容与注释符号之间加1个空格。适用场景：解释单个变量、简单逻辑、临时修改说明，注释需紧跟被注释代码，位于代码上方或右侧（右侧注释与代码之间加2个空格）。示例：正确（#用户年龄，用于判断成年状态；intage=18;//用户年龄，默认成年）；错误（#注释；age=18//注释）。2.3.2多行注释使用对应语言的多行注释符号（Python用三重引号，Java、JavaScript用/**/），注释内容缩进与被注释代码一致，首行和尾行单独成行，中间每行注释对齐。适用场景：解释类、函数、复杂逻辑块、文件说明，文件注释需包含版权信息、文件名、作者、历史版本、文件功能等内容。2.3.3文档注释所有公有模块、函数、类、方法都必须添加文档注释，文档注释需明确说明功能、参数（名称、类型、含义）、返回值（类型、含义）、异常/错误信息、边界条件等，可使用文档生成工具（如Doxygen、Sphinx）生成API文档。示例（Python）：

defcalculate_total_amount(price:float,quantity:int)->float:

"""计算商品总金额

Args:

price:商品单价（浮点数）

quantity:商品数量（整数，大于0）

Returns:

float:商品总金额（price*quantity）

Raises:

ValueError:当quantity小于等于0时抛出

"""

ifquantity<=0:

raiseValueError("商品数量必须大于0")

returnprice*quantity2.4代码逻辑规范单一职责：每个函数、类仅负责一个核心功能，避免一个函数/类包含多个不相关的逻辑，函数长度控制在50行以内，类长度控制在300行以内（特殊场景可适当调整）。避免冗余：禁止重复编写相同逻辑，可封装为函数、工具类复用；禁止存在无效代码（如未使用的变量、未调用的函数、注释掉的代码）。条件判断：条件表达式简洁明了，避免复杂嵌套（嵌套层数不超过3层）；多条件判断优先使用switch/case（如Java、JavaScript）或字典映射（如Python），提升可读性；禁止使用过于复杂的三目运算符。循环逻辑：循环条件清晰，避免无限循环；循环体内逻辑简洁，避免在循环中创建对象、频繁IO操作，大数据量循环需考虑性能优化（如分页处理）；临时迭代变量可使用单个字母（如i、j、k），但需确保无歧义。异常处理：禁止吞掉异常（try-catch不处理逻辑），需明确受检异常与非受检异常的处理边界，异常捕获后需记录日志（说明异常原因、发生位置），对外接口返回友好提示，避免暴露堆栈信息；异常捕获需精准，避免使用catch-all（如catch(Exceptione)），优先捕获具体异常类型。2.5安全性规范输入校验：所有用户输入（前端传参、接口调用参数、外部数据）必须进行校验，包括数据类型、长度、格式、范围，规避SQL注入、XSS攻击、参数篡改等风险。敏感数据：密码、手机号、身份证号等敏感数据，需加密存储（如密码使用MD5、SHA256加密），禁止明文存储；禁止在日志中打印敏感数据，禁止硬编码密钥、密码等敏感信息（统一存入配置中心）。接口安全：接口调用需进行权限校验，避免未授权访问；对外接口需设置超时时间，防止请求阻塞；避免暴露内部接口细节，返回数据仅包含必要信息。依赖安全：引入第三方依赖时，优先选择官方、稳定、维护活跃的依赖，锁定依赖版本（如package.json使用lock文件，Maven指定版本号），禁止引入高风险、低维护的依赖，定期更新依赖以修复安全漏洞。2.6版本控制规范分支管理：统一采用“主分支（main）+开发分支（dev）+特性分支（feature）+修复分支（hotfix）”策略，特性分支从dev创建，修复分支从main创建，合并前需经过代码审查，禁止直接向main分支提交代码。提交信息：遵循“类型：描述”格式，类型包括feat（新增功能）、fix（修复bug）、docs（更新文档）、style（格式调整，不影响功能）、refactor（重构）、test（新增/修改测试用例），描述简洁明了，说明提交目的，避免“修改bug”“更新代码”等无效描述。代码审查：提交代码后需进行代码审查，审查重点包括编码规范符合性、逻辑正确性、安全性、可读性，通过“以审代教”让规范深入人心。3.各语言专项编码规范3.1Python编码规范（遵循PEP8）命名：包名、模块名、变量名、函数名用snake_case；类名、异常名用PascalCase（异常名以Error/Exception结尾）；常量名用UPPER_SNAKE_CASE；私有成员用单下划线前缀，私有变量用双下划线前缀（避免与Python保留名冲突），禁止使用双下划线开头和结尾的命名。格式：缩进用4个空格；每行代码不超过79个字符（注释不超过72个字符）；导入顺序：标准库→第三方库→自定义库，导入时禁止使用通配符（fromxxximport*），模块级双下划线名称（如__all__）需放在导入语句之后。注释：文档注释用三重双引号，位于函数、类、模块的第一行；单行注释用#，避免行内注释过多；禁止注释掉的代码留存，无用代码直接删除。特殊要求：避免使用lambda表达式定义复杂逻辑；列表推导式简洁使用，避免嵌套过深；函数参数优先使用位置参数，关键字参数用于可选参数；禁止在循环中使用del、pop修改列表长度。3.2Java编码规范（遵循GoogleJavaStyle）命名：包名全部小写（如ject.service）；类名、接口名用PascalCase；方法名、变量名用camelCase；常量名用UPPER_SNAKE_CASE；枚举类名用PascalCase，枚举值用UPPER_SNAKE_CASE。格式：缩进用4个空格；每行代码不超过100个字符；左大括号紧跟语句末尾，右大括号单独成行，与对应语句对齐；方法参数列表换行时，每个参数单独一行，缩进与方法名对齐。注释：文档注释用/***/，包含@param、@return、@throws等标签；单行注释用//，位于被注释代码上方；类注释需说明类的功能、作者、创建日期；方法注释需说明功能、参数、返回值、异常信息。特殊要求：成员变量私有化（private），通过getter/setter方法访问；避免使用static全局变量；异常处理需精准，捕获异常后需记录日志；代码中禁止使用魔法数字，全部定义为常量；接口仅定义方法，不实现逻辑。3.3JavaScript编码规范（遵循AirbnbJavaScriptStyle）命名：变量名、函数名用camelCase；类名、构造函数用PascalCase；常量名用UPPER_SNAKE_CASE；私有成员用下划线前缀（_privateMethod）；文件、模块名用kebab-case或camelCase，项目内统一。格式：缩进用2个空格；每行代码不超过100个字符；左大括号紧跟语句末尾，右大括号单独成行；箭头函数简洁使用，单参数可省略括号，单语句可省略大括号。注释：文档注释用/***/，用于类、函数、模块；单行注释用//，解释复杂逻辑；禁止注释掉的代码留存；避免冗余注释，代码本身可清晰表达的逻辑无需注释。特殊要求：优先使用let、const，禁止使用var；避免全局变量污染，可使用闭包、模块导出；Promise异步逻辑优先使用async/await，避免嵌套回调；数组、对象字面量简洁使用，避免冗余写法；输入参数需进行类型校验。4.工程结构规范4.1通用工程结构工程结构需清晰、规范，按“功能模块”或“分层架构”组织，便于文件查找和维护，禁止文件乱放，核心目录结构如下（可根据项目类型调整）：根目录：src（源代码）、test（测试代码）、docs（文档）、config（配置文件）、utils（工具类）、logs（日志）、README.md（项目说明）。src目录：按分层或模块划分（如后端：controller、service、dao、model；前端：components、pages、utils、api、assets）。test目录：与src目录结构对应，用于存放单元测试、集成测试代码，测试文件命名与被测试文件一致，后缀加Test（如UserServiceTe