程序代码编写规范

程序代码编写规范1.总则1.1目的为统一代码编写标准，提高代码可读性、可维护性、可复用性，降低团队协作成本，减少潜在bug，确保项目代码质量的一致性和稳定性，特制定本规范。本规范适用于所有开发人员在项目开发过程中的代码编写、修改、评审等相关工作。1.2适用范围本规范适用于团队所有开发项目，包括前端、后端、移动端等各类程序代码，涵盖代码编写、注释、格式、命名、安全等各个环节，所有开发人员必须严格遵守，代码评审人员需以此为依据进行评审。1.3核心原则可读性优先：代码是写给人看的，其次才是机器执行，确保他人能快速理解代码逻辑和用途。一致性原则：同一项目、同一模块的代码，在命名、格式、注释等方面保持统一，避免混乱。可维护性原则：代码结构清晰、逻辑简洁，便于后续修改、扩展和问题排查。安全性原则：规避常见安全隐患（如注入、越界、空指针等），确保代码运行安全。简洁性原则：避免冗余代码，不写无用代码、重复代码，用最简洁的方式实现功能。2.命名规范2.1通用规则采用有意义的命名，名称需准确反映变量、函数、类、常量等的用途，避免使用无意义的缩写（如a、b、x、temp等，特殊场景除外）。严格区分大小写，遵循对应语言的命名惯例（如Java、C#采用驼峰命名，Python采用下划线命名），禁止大小写混用且无意义。禁止使用关键字、保留字作为命名（如class、int、for、if等），避免与系统内置函数、类名冲突。命名长度适中，过长易冗余，过短无意义，一般控制在3-20个字符之间。2.2变量命名局部变量：遵循对应语言命名惯例，首字母小写，后续单词首字母大写（驼峰）或用下划线连接（下划线命名），如userName（驼峰）、user_name（下划线）。全局变量：建议在命名前添加前缀（如g_），明确区分全局与局部，如g_globalConfig。常量命名：全部大写，多个单词之间用下划线连接，如MAX_PAGE_SIZE、DB_CONNECTION_URL。布尔变量：命名需体现“是否”含义，建议使用is、has、can等前缀，如isLogin、hasPermission、canEdit。2.3函数/方法命名采用动词+名词的结构，明确表达函数的功能，如getUserInfo（获取用户信息）、saveOrder（保存订单）、deleteById（根据ID删除）。避免使用模糊的动词，如doSomething、handleData，需准确描述具体操作。函数命名遵循对应语言惯例，如Java、C#采用驼峰命名（首字母小写），Python采用下划线命名。工具类函数：可添加模块前缀，明确所属功能，如stringUtil.isEmpty、dateUtil.formatDate。2.4类/接口命名类命名：采用名词或名词短语，首字母大写，后续单词首字母大写（驼峰命名），如User、OrderService、UserController。接口命名：建议在类命名基础上添加前缀I（部分语言惯例），或体现“行为”含义，如IUserService、LoginService。抽象类命名：建议添加前缀Abstract，如AbstractBaseService。异常类命名：建议添加后缀Exception，如UserNotFoundException、ParamErrorException。2.5包/模块命名采用小写字母，多个单词之间用点（.）或斜杠（/）分隔（根据语言惯例），如ject.controller（Java包）、src/utils（Python模块）。包/模块命名需体现功能分层或业务模块，如controller（控制层）、service（服务层）、dao（数据访问层）、utils（工具类）。禁止使用中文、特殊字符作为包/模块名称，避免使用数字开头。3.代码格式规范3.1缩进统一使用4个空格作为缩进（禁止使用制表符Tab），确保不同编辑器打开时格式一致。代码块（如if、for、while、class、function等）的内容必须缩进，缩进层级清晰，体现代码逻辑结构。嵌套代码块需逐层缩进，避免缩进混乱，如if嵌套、循环嵌套，每层缩进4个空格。3.2换行每个语句单独一行，禁止多个语句写在同一行（如inta=1;intb=2;需分开写）。函数定义、类定义、代码块（if、for等）的左大括号{紧跟语句后，右大括号}单独一行，且与对应语句对齐，如：正确示例：if(isLogin){...}错误示例：if(isLogin){...}或if(isLogin){...}当函数参数过多时，需换行显示，每个参数单独一行，对齐方式保持一致。表达式过长时，需在运算符处换行，换行后缩进对齐，便于阅读，如：intresult=a+b+c+d+e+f;可换行为：intresult=a+b+c+d+e+f;3.3空格运算符两侧各加一个空格，如a+b、x=10、i>5，禁止a+b、x=10、i>5。逗号（,）、分号（;）后加一个空格，逗号前不加空格，如getUser(id,name,age)、for(inti=0;i<10;i++)。括号内侧不加空格，如if(isLogin)、function(a,b)，禁止if(isLogin)、function(a,b)。函数名与括号之间不加空格，如getUser()，禁止getUser()。注释符号与注释内容之间加一个空格，如//这是注释，禁止//这是注释。3.4空行类的成员之间（属性与方法、方法与方法之间）加一个空行，区分不同成员。函数内部，不同逻辑块之间加一个空行，分隔不同功能的代码段。包导入语句与类定义之间加一个空行，类定义与第一个方法之间加一个空行。禁止连续多个空行（最多保留一个空行），避免代码冗余。4.注释规范4.1注释原则注释需简洁、准确、有用，避免无意义的注释（如//定义变量a、//循环开始）。注释与代码同步更新，代码修改后，对应的注释必须及时修改，避免注释与代码不一致。优先通过清晰的命名和简洁的代码表达逻辑，减少不必要的注释，避免过度注释。禁止使用中文拼音、乱码、无意义字符作为注释内容，注释语言统一为中文（特殊场景可使用英文）。4.2类注释每个类（包括接口、抽象类）必须添加类注释，位于类定义上方，说明类的用途、作者、创建时间、修改记录等。类注释格式统一，建议包含以下内容：/***类描述：用户控制器，负责处理用户相关的请求（如登录、注册、个人信息修改）*作者：XXX*创建时间：2026-03-25*修改记录：2026-03-26XXX新增用户注销功能*/4.3方法注释每个公共方法（public）必须添加方法注释，位于方法定义上方，说明方法的功能、参数、返回值、异常信息等。方法注释需包含以下核心内容：/***方法描述：根据用户ID获取用户详细信息*@paramuserId用户ID，非空，长度为1-32位字符串*@returnUser用户详细信息对象，包含用户名、手机号、邮箱等*@throwsUserNotFoundException当用户ID不存在时抛出异常*/私有方法（private）可根据复杂度添加注释，复杂逻辑必须添加注释说明。4.4代码行注释针对复杂逻辑、关键步骤、难以理解的代码行，添加行注释，说明代码的作用、逻辑思路。行注释位于代码行上方或右侧，右侧注释需与代码保持一定距离（至少4个空格），如：//计算总金额，扣除优惠后的值doubletotal=price*count-discount;//最终支付金额禁止对简单、直观的代码添加行注释（如inta=10;//定义变量a为10）。4.5注释格式单行注释：使用//开头，注释内容紧跟空格，适用于行注释、简单说明。多行注释：使用/*...*/包裹，适用于类注释、方法注释、复杂逻辑的详细说明，禁止多行注释嵌套。文档注释：遵循对应语言的文档注释规范（如Java的/**...*/），可通过工具生成文档。5.代码逻辑规范5.1函数/方法逻辑一个函数/方法只负责一个功能，避免“大函数”（建议函数代码长度不超过100行），复杂功能可拆分为多个小函数，提高复用性和可读性。函数参数不宜过多（建议不超过5个），参数过多时可封装为对象传递。函数返回值需明确，避免返回多种类型（特殊场景除外），返回值含义清晰，便于调用者理解。禁止在函数内部修改传入的参数（引用类型除外，需明确说明），避免副作用。5.2条件判断逻辑条件判断语句（if-else、switch）逻辑清晰，避免嵌套过深（建议嵌套不超过3层），嵌套过深时可拆分为函数或调整逻辑。if-else语句中，优先处理正常逻辑，异常逻辑放在else中，如：正确示例：if(isSuccess){执行成功逻辑}else{执行失败逻辑}禁止使用复杂的条件表达式，可将复杂条件封装为布尔变量，提高可读性，如：booleanisQualified=(age>=18)&&(score>=60)&&(isActive);if(isQualified){...}switch语句需包含default分支，处理异常情况，case分支需添加break（除非有特殊逻辑），避免穿透。5.3循环逻辑循环语句（for、while、do-while）需明确循环条件，避免出现死循环（如while(true)需确保内部有退出逻辑）。循环体内代码简洁，避免在循环内做大量耗时操作（如数据库查询、文件读写），可将耗时操作移至循环外。避免使用嵌套循环（建议不超过2层），嵌套循环可通过优化逻辑、使用集合工具类等方式简化。循环变量命名规范，明确变量含义（如i、j、k仅用于简单循环，复杂循环需使用有意义的命名）。5.4异常处理逻辑异常处理需精准，避免捕获所有异常（如try-catch(Exceptione)），应捕获具体异常类型，针对性处理。异常捕获后，需做具体处理（如日志记录、错误提示、回滚操作），禁止捕获异常后不做任何处理（空catch）。抛出异常时，需添加详细的异常信息，说明异常原因，便于问题排查，如thrownewUserNotFoundException("用户ID："+userId+"不存在")。合理使用异常机制，避免用异常替代条件判断，如不要用try-catch捕获空指针异常，应提前判断对象是否为null。6.安全规范6.1输入验证所有用户输入（如接口参数、表单提交、URL参数）必须进行验证，包括合法性、长度、格式、范围等，避免注入攻击、越界等问题。验证逻辑需在前端和后端同时实现，后端验证为核心，避免前端验证被绕过。禁止直接使用用户输入的内容拼接SQL、命令等，需使用参数化查询、预编译语句等方式，防止SQL注入、命令注入。6.2数据安全敏感数据（如密码、手机号、身份证号）需进行加密存储（如密码使用MD5、SHA256等加密算法），禁止明文存储。敏感数据传输时，需使用加密协议（如HTTPS），避免数据泄露。禁止在日志中打印敏感数据（如密码、token、身份证号），避免日志泄露。6.3其他安全注意事项避免使用硬编码（如密码、密钥、URL等），应将硬编码内容配置在配置文件中，便于维护和修改。禁止使用过期、不安全的依赖包、组件，及时更新依赖，规避已知安全漏洞。控制代码权限，敏感操作（如删除、修改）需添加权限校验，避免越权操作。7.可复用性规范重复出现的代码片段（如数据校验、日期格式化、异常处理），需封装为工具类、公共方法，提高复用性，避免重复开发。公共方法、工具类需通用，避免绑定具体业务逻辑，便于在多个模块中复用。合理使用继承、接口、抽象类等特性，提取公共逻辑，实现代码复用和扩展。避免复制粘贴代码，复制粘贴的代码需及时封装，否则后续修改需同步修改所有副本，易出现遗漏。8.代码