代码编写规范

代码编写规范一、总则1.目的：为统一代码编写标准，提高代码可读性、可维护性、可扩展性，降低团队协作成本，减少潜在bug，确保项目代码质量与长期可迭代性。2.适用范围：本规范适用于所有开发人员（前端、后端、移动端）在项目开发、迭代、修复过程中编写的所有代码（包括业务代码、工具类、配置文件、测试用例等）。3.核心原则：遵循“清晰易懂、简洁高效、规范统一、可复用”，优先保证代码的可读性，再追求执行效率；禁止编写冗余、晦涩、无意义的代码。二、通用基础规范2.1编码格式1.编码格式：统一使用UTF-8编码，禁止使用GBK等其他编码格式，避免出现中文乱码问题。2.换行与缩进：采用4个空格缩进（禁止使用Tab缩进），每个逻辑块结束后进行换行；一行代码长度控制在80-120字符内，超长代码需合理换行（优先在运算符、逗号后换行，保持语法清晰）。3.空行规范：类与类、方法与方法、代码块（if/for/while等）之间保留1个空行；方法内部不同逻辑段落之间保留1个空行；禁止连续出现2个及以上空行，禁止行首、行尾出现多余空格。4.符号规范：所有标点符号使用英文半角符号（逗号、分号、括号、引号等）；赋值、比较、逻辑运算等运算符前后各保留1个空格（如inta=1;而非inta=1;）；括号内侧不保留空格（如if(a>0)而非if(a>0)）。2.2命名规范核心原则：命名需语义化，见名知意，禁止使用无意义的字母（如a、b、c）、数字或拼音缩写（特殊场景除外），避免歧义；统一采用对应语言的命名风格，不混合使用多种风格。1.类命名：采用帕斯卡命名法（PascalCase），首字母大写，后续每个单词首字母均大写，命名以名词或名词短语为主（如UserController、OrderService）。2.方法命名：采用驼峰命名法（camelCase），首字母小写，后续每个单词首字母大写，命名以动词或动词短语为主，体现方法的功能（如getUserInfo、createOrder）；查询类方法前缀用get/select，新增类用add/create，修改类用update，删除类用delete/remove，判断类用is/has。3.变量命名：采用驼峰命名法（camelCase），首字母小写，语义清晰，避免使用关键字（如int、class、static等）；局部变量尽量简洁但不模糊（如intcount而非intc），成员变量可根据语言规范添加前缀（如Java中成员变量前缀m_，但需团队统一）。4.常量命名：采用全大写字母，单词之间用下划线分隔（UPPER_CASE_SNAKE_CASE），命名需体现常量的含义（如MAX_PAGE_SIZE、USER_STATUS_ACTIVE）；禁止使用魔法数字、魔法字符串，所有固定值均定义为常量。5.其他命名：接口命名前缀统一用I（如IUserService）；枚举类命名后缀用Enum（如UserStatusEnum）；工具类命名后缀用Util（如DateUtil）；配置类命名后缀用Config（如DataSourceConfig）。2.3注释规范核心原则：注释需简洁、准确、有用，避免冗余注释（如//定义变量a）；注释与代码同步更新，禁止注释与代码不一致；优先使用中文注释，特殊场景（如通用工具类）可使用英文注释。1.类注释：每个类顶部必须添加类注释，说明类的功能、作者、创建时间、修改记录（可选），格式统一（如Java使用/**...*/，前端使用//或/*...*/）。2.方法注释：每个公共方法（public）顶部必须添加方法注释，说明方法的功能、参数含义（参数名+说明）、返回值含义、异常说明（可选）；私有方法（private）根据复杂度添加注释，简单方法可省略。3.代码块注释：复杂逻辑、关键业务逻辑、不易理解的代码块（如算法、条件判断），需在代码块上方添加注释，说明逻辑意图；禁止在代码行中间添加注释（影响可读性）。4.注释禁忌：禁止注释无效代码（如需保留无效代码，需说明原因并标注删除时间）；禁止使用侮辱性、无关性注释；禁止复制粘贴代码后不修改对应注释。三、语言专属规范3.1Java代码规范1.包命名：采用全小写字母，以公司域名倒置开头，后续按模块划分（如ject.user、ject.order），禁止使用大写字母或特殊符号。2.类与接口：类需遵循单一职责原则，一个类只负责一个功能；接口只定义方法，不实现具体逻辑；抽象类命名前缀用Abstract（如AbstractBaseService）。3.方法与变量：方法参数个数控制在5个以内，超过5个建议使用实体类封装；成员变量私有化（private），通过getter/setter方法访问，禁止直接暴露成员变量；禁止使用static修饰成员变量（常量除外）。4.异常处理：禁止捕获异常后不处理（如try-catch中只写e.printStackTrace()）；异常需精准捕获，避免使用catch(Exceptione)捕获所有异常；自定义异常需继承Exception或RuntimeException，命名后缀用Exception（如BusinessException）。5.其他：禁止使用System.out.println()打印日志，统一使用日志框架（如Logback、Log4j）；集合初始化时需指定初始容量（如List<String>list=newArrayList<>(10)）；避免使用null判断，优先使用Optional类处理空值。3.2前端代码规范（Vue/React）1.文件命名：组件文件采用帕斯卡命名法（如UserList.vue、OrderDetail.jsx）；工具文件、utils文件采用驼峰命名法（如dateFormat.js）；样式文件与组件文件同名（如UserList.scss）。2.组件规范：组件遵循单一职责，一个组件只负责一个功能；组件props需定义类型、默认值、校验规则，禁止传递无关props；组件事件命名统一用kebab-case（如@click="handleSubmit"，而非@click="handle_submit"）。3.代码逻辑：模板中禁止写复杂逻辑（如if-else嵌套、循环嵌套），复杂逻辑提取到methods或computed中；computed用于处理依赖响应式数据的计算，methods用于处理事件和业务逻辑，watch用于监听数据变化（避免滥用）。4.样式规范：样式采用scoped隔离（避免样式污染）；样式命名采用BEM命名法（如.block__element--modifier）；禁止使用!important（特殊场景需说明原因）；优先使用flex/grid布局，避免使用float布局。5.其他：禁止在模板中直接使用{{}}渲染未处理的原始数据（如日期、金额），需通过过滤器或工具函数处理；路由命名与组件命名保持一致，路由路径采用kebab-case（如/user/list）；禁止引入未使用的依赖、组件。3.3Python代码规范1.文件命名：采用全小写字母，单词之间用下划线分隔（如user_service.py、date_util.py），禁止使用大写字母或特殊符号。2.缩进与换行：严格使用4个空格缩进，禁止使用Tab；函数、类之间保留2个空行；导入模块需按“标准库→第三方库→自定义库”的顺序排列，不同类型之间保留1个空行。3.变量与函数：变量、函数命名采用全小写字母，单词之间用下划线分隔（如user_name、get_user_info）；类命名采用帕斯卡命名法；禁止使用单字符变量（除常见的i、j、k用于循环计数外）。4.代码逻辑：禁止使用eval()函数（存在安全风险）；条件判断中，避免使用复杂的逻辑表达式，可提取为变量；循环中避免重复执行耗时操作（如数据库查询）；函数参数优先使用关键字参数，提高可读性。5.其他：字符串拼接优先使用f-string（Python3.6+），避免使用+号拼接；异常处理需精准，捕获异常后需记录日志；禁止在代码中使用print()调试，优先使用logging模块。四、安全规范1.输入校验：所有用户输入（如表单提交、接口参数）必须进行校验，禁止直接使用用户输入的数据进行数据库操作、文件操作，防止SQL注入、XSS攻击、文件上传漏洞。2.敏感数据：禁止在代码中硬编码敏感数据（如数据库密码、密钥、token、手机号、身份证号），需通过配置文件、环境变量获取；敏感数据传输、存储需加密（如密码加密存储，不明文保存）。3.权限控制：接口、方法需添加权限校验，禁止未授权访问；禁止在代码中关闭权限校验（测试环境除外，且需标注并在上线前删除）。4.安全禁忌：禁止使用不安全的加密算法（如MD5、DES），优先使用SHA-256、AES等安全算法；禁止暴露系统敏感信息（如异常堆栈信息、服务器地址、数据库信息）给前端用户。五、可维护性与可复用性规范1.代码复用：重复出现2次及以上的代码，需提取为工具类、公共方法或组件，禁止复制粘贴；公共方法、组件需考虑通用性，避免绑定具体业务逻辑。2.逻辑拆分：复杂业务逻辑需拆分为多个小方法、小组件，每个方法、组件只负责一个功能，降低代码复杂度；禁止一个方法、一个类过于庞大（如方法代码超过100行，类代码超过1000行）。3.版本控制：代码提交需遵循规范，提交信息需清晰（如“feat:新增用户注册功能”“fix:修复订单查询bug”）；禁止一次性提交大量无关代码，每次提交只对应一个功能或一个bug修复。4.兼容性：代码编写需考虑版本兼容性（如Java版本、前端浏览器版本、Python版本），禁止使用版本专属的语法、API，如需使用需添加版本判断。六、检查与处罚1.自查：开发人员在提交代码前，需自行对照本规范检查代码，确保符合规范；2.代码评审：团队进行代码评审时，需重点检查代码是否符合本