代码规范文档

代码规范文档1.文档目的为统一团队代码编写标准，提升代码可读性、可维护性、可扩展性，降低协作成本，减少潜在Bug，确保项目代码质量的一致性和规范性，特制定本规范。本规范适用于团队所有开发人员、测试人员及相关协作人员，覆盖项目全生命周期的代码编写、评审、修改、提交等环节，所有相关人员必须严格遵守。2.通用代码规范2.1命名规范命名需遵循“清晰易懂、语义明确、前后一致”原则，禁止使用无意义字符、拼音（特殊场景除外）、缩写（通用缩写如API、URL除外），杜绝歧义，确保他人能通过命名快速理解变量、函数、类的用途。变量命名：采用小驼峰命名法（lowerCamelCase），首字母小写，后续单词首字母大写，如userName、orderTotalAmount；禁止使用单字母变量（循环变量如i、j、k除外，且需确保作用域清晰），禁止使用下划线连接（除非适配第三方规范）。函数/方法命名：采用小驼峰命名法，动词开头，明确表达函数功能，如getUserInfo、submitOrder；避免使用模糊性命名，如doSomething、handleData（需明确具体操作）。类命名：采用大驼峰命名法（UpperCamelCase），首字母大写，后续单词首字母大写，体现类的职责，如UserController、OrderService；禁止使用复数形式（集合类除外，如UserList）。常量命名：采用全大写字母，下划线连接，语义清晰，如MAX_PAGE_SIZE、ORDER_STATUS_PAID；常量需集中定义，避免分散在代码中重复定义。注释命名：注释语言统一为中文，简洁明了，避免冗余；注释内容需与代码逻辑一致，禁止注释与代码脱节。2.2代码格式规范代码格式需统一，确保视觉整洁，便于阅读，减少因格式差异导致的理解成本，所有代码需通过团队指定的格式化工具（如Prettier、ESLint等）格式化后提交。缩进：采用4个空格缩进（禁止使用Tab缩进），嵌套层级清晰，每一层嵌套需缩进一次；switch-case语句中，case、default需缩进一次，与switch对齐。换行：每个独立的代码块（函数、类、循环、条件判断等）前后需空一行；每个语句单独占一行，禁止多个语句写在同一行（如leta=1;letb=2;需拆分为两行）；运算符前后需加空格，如a+b、x===y，禁止a+b、x===y。括号：大括号{}需与关键字（if、for、function等）同行，左括号后空一格，右括号前空一格；如if(condition){...}，禁止if(condition){...}或if(condition){...}；空括号内无需空格，如function(){...}。空行：函数内部，逻辑块之间空一行；类内部，属性与方法之间、方法与方法之间空一行；文件末尾需保留一个空行；禁止连续空多行。引号：统一使用单引号''（JSON格式除外，JSON需使用双引号""）；禁止单引号、双引号混用。2.3注释规范注释是代码的补充说明，目的是帮助他人理解代码逻辑，减少维护成本；注释需简洁、准确，避免冗余，禁止注释无关内容，禁止注释错误代码。类注释：类定义上方需添加注释，说明类的职责、用途、作者、创建时间（可选），复杂类需补充核心逻辑说明；如：

/**

*用户控制器

*负责处理用户相关的请求（登录、注册、个人信息修改等）

*@author开发人员姓名

*@date2026-03-23

*/

classUserController{...}函数/方法注释：函数定义上方需添加注释，说明函数的功能、参数含义、返回值类型及含义、异常情况（可选）；如：

/**

*获取用户个人信息

*@param{number}userId-用户ID（必传）

*@returns{object}用户信息对象（包含userName、age、phone等字段）

*@throws{Error}当userId不存在或格式错误时抛出异常

*/

functiongetUserInfo(userId){...}行内注释：针对复杂逻辑、关键代码、不易理解的语句添加行内注释，注释需在代码右侧，与代码之间空两格；禁止对简单、易懂的语句添加行内注释（如leta=1;//定义变量a无需注释）。注释更新：修改代码时，需同步更新对应的注释，确保注释与代码逻辑一致；禁止保留过时、错误的注释。2.4代码质量规范简洁性：代码需简洁明了，避免冗余代码（如重复的判断条件、重复的逻辑块）；可通过抽取公共函数、公共变量，减少代码重复。可读性：优先保证代码可读性，再追求简洁；避免使用过于复杂的表达式、嵌套层级过多（嵌套层级不超过4层）；如嵌套过多，可拆分为多个函数。健壮性：需考虑异常场景（如参数为空、数据格式错误、网络异常等），添加异常处理逻辑（try-catch、参数校验等）；禁止直接使用未校验的参数。可维护性：代码逻辑清晰，模块划分合理，每个函数、类的职责单一，避免“一个函数干所有事”；便于后续修改和扩展。禁止事项：禁止使用eval函数（存在安全风险）；禁止使用未定义的变量、函数；禁止硬编码（如固定的IP、端口、常量等，需统一定义为常量）；禁止写死逻辑（需考虑扩展性）。3.语言特定代码规范3.1JavaScript/TypeScript规范变量声明：优先使用const（常量）、let（变量），禁止使用var（存在变量提升、作用域混乱问题）；const用于声明不可修改的变量，let用于声明可修改的变量。箭头函数：简洁逻辑可使用箭头函数，复杂逻辑（如包含this指向、多个语句）建议使用普通函数；避免箭头函数滥用导致的this指向问题。对象/数组：对象字面量尽量简洁，属性名无需加引号（特殊字符除外）；数组初始化优先使用[]，对象初始化优先使用{}，禁止使用newArray()、newObject()。异步处理：优先使用async/await（简洁、易读），避免回调地狱；async函数需处理异常（try-catch）。类型校验：TypeScript需严格定义类型，禁止使用any类型（特殊场景除外，需添加注释说明）；接口（interface）命名采用大驼峰，后缀可加Interface（如UserInterface）。3.2Java规范包命名：采用全小写字母，以公司域名倒置开头，后续按模块划分，如ject.user；禁止使用大写字母、特殊字符。类与接口：接口命名采用大驼峰，后缀加Interface（如UserServiceInterface）；抽象类命名前缀加Abstract（如AbstractUserService）。方法与变量：遵循通用命名规范，方法参数需添加注释，返回值需明确；成员变量需私有化（private），通过getter/setter方法访问，禁止直接暴露成员变量。异常处理：捕获异常时，需明确异常类型，禁止捕获所有异常（catch(Exceptione)）；异常处理需有具体逻辑（如日志记录、提示信息），禁止空catch块。代码结构：每个类单独一个文件，文件名与类名一致；导入包需按需导入，禁止导入无用包；代码末尾禁止保留未使用的导入、变量、方法。3.3Python规范缩进：严格遵循PEP8规范，采用4个空格缩进，禁止使用Tab缩进；嵌套层级不超过4层。命名：变量、函数采用小驼峰或下划线命名（推荐下划线，如user_name、get_user_info）；类采用大驼峰命名；常量采用全大写下划线命名。导入规范：导入顺序为“标准库→第三方库→自定义库”，不同类型导入之间空一行；禁止导入无用模块，禁止使用fromxxximport*（会导致命名冲突）。代码长度：每行代码长度不超过80个字符（特殊情况可放宽至120个字符），过长代码需换行，换行时优先在运算符后换行，保持逻辑连贯。注释：类、函数注释采用文档字符串（docstring），使用三引号包裹，说明职责、参数、返回值；行内注释使用#，与代码之间空两格。4.版本控制规范4.1分支管理主分支（main/master）：用于存放正式发布的代码，禁止直接在主分支上修改、提交代码；主分支代码需保持稳定，可直接用于生产环境。开发分支（develop）：用于团队日常开发，所有开发人员在开发分支上进行协作；开发完成后，通过合并请求（MR/PR）合并到主分支。功能分支（feature/*）：用于开发单个功能，命名格式为feature/功能名称（如feature/user-register）；功能开发完成后，合并到develop分支，合并后删除该功能分支。修复分支（bugfix/*）：用于修复线上或开发中的Bug，命名格式为bugfix/bug描述（如bugfix/login-error）；修复完成后，合并到develop和main分支，合并后删除该修复分支。4.2提交规范提交信息需清晰、规范，便于查看提交记录，追溯代码变更原因；提交信息格式为：类型:描述（可选：详细说明），类型统一规范，禁止随意填写。类型说明：

feat：新增功能（如feat:新增用户注册功能）fix：修复Bug（如fix:修复登录时密码加密异常问题）docs：修改文档（如docs:更新代码规范文档）style：修改代码格式（不影响代码逻辑，如style:格式化代码，调整缩进）refactor：重构代码（不新增功能、不修复Bug，如refactor:抽取公共函数，优化代码结构）test：添加/修改测试用例（如test:新增用户登录测试用例）chore：构建、依赖等无关代码逻辑的修改（如chore:更新依赖包版本）提交要求：每次提交只对应一个功能或一个Bug修复，禁止一次提交多个不相关的修改；提交前需检查代码格式、注释是否符合规范，确保代码可运行；禁止提交无用代码、测试代码、临时文件（如IDE配置文件、日志文件等）。5.代码评审规范评审范围：所有代码提交（尤其是合并到develop、main分支的代码）必须经过评审，禁止未经评审直接合并。评审内容：检查代码是否符合本规范（命名、格式、注释等）；检查代码逻辑是否清晰、健壮，是否存在Bug、冗余代码；检查代码是否具有可维护性、可扩展性；检查注释是否完整、准确。评审流程：开发人员提交合并请求（MR/PR），指定评审人员；评审人员在24小时内完成评审，提出修改意见；开发人员根据意见修改代码，修改完成后重新提交评审；评审通过后，由评审人员合并代码。评审要