代码编写规范文档

代码编写规范文档前言：代码编写规范的核心目标是保证代码的可读性、可维护性、可复用性和一致性，降低团队协作成本与后期维护成本，同时提升代码质量、减少潜在Bug。本文档精选通用规范及主流编程语言核心规范，兼顾通用性与实用性，适用于各类研发团队及个人开发，可直接落地执行，也可根据项目实际需求灵活调整。一、通用核心规范（全语言适用）1.1命名规范（最基础且关键）命名的核心原则是“见名知义、简洁规范”，禁止使用拼音、无意义缩写或单个字符（常见标准缩写如id、URL、API除外），统一使用英文命名，确保团队内命名风格一致。变量/函数：采用小驼峰命名法（camelCase），如userName、calculateTotal、fetchUserInfo，避免使用模糊命名（如a、temp、data）。常量：采用全大写字母+下划线分隔（UPPER_SNAKE_CASE），如MAX_COUNT、PI、MAX_TIMEOUT，明确常量的语义范围。类/结构体：采用大驼峰命名法（PascalCase），如UserProfile、DatabaseConnection、UserService，类名应体现其核心功能。文件/目录：前端优先使用小写+横杠（kebab-case），如user-center、login-form.vue；后端可采用小写+横杠或小驼峰，如novel-system、userController，避免大小写混合。私有成员：前缀加下划线（_xxx），如_privateMethod、_userInfo，区分公有与私有成员，提升代码可读性。1.2格式规范（保证代码整洁有序）缩进：全项目统一缩进方式，优先选择4个空格（如Python、Java）或2个空格（如前端Vue/React），禁止混合使用空格和制表符（Tab），避免缩进混乱。行长度：单条代码行长度控制在80-120个字符，超长行需合理换行，优先在二元运算符前换行，或利用括号、引号进行隐式换行，确保一行只表达一个逻辑。空行：逻辑相关的代码块之间添加1个空行，如函数之间、类之间、不同逻辑模块之间；避免连续空行，代码文件末尾禁止留空行。符号规范：逗号、分号后加1个空格，运算符两侧各加1个空格（如a+b、x==y）；括号内侧不加空格（如if(x>0)，而非if(x>0)）；代码文件编码统一为UTF-8。1.3注释规范（避免冗余，突出重点）注释的核心是“解释为什么做，而非做了什么”，代码本身应尽量清晰，避免过度注释或无注释，同时禁止保留注释掉的代码（无用代码需直接删除）。类/函数注释：类注释需说明类的功能、设计思路；函数/方法注释需明确功能、入参（类型、含义）、返回值（类型、含义）、异常场景，推荐使用规范文档注释（如Java的Javadoc、Python的docstring）。行注释：仅用于解释复杂逻辑、特殊业务规则或临时说明，标注在代码上方或右侧，避免每行都加注释；复杂逻辑需逐段注释，说明设计意图。临时注释：使用//TODO:标注待优化、待完善的代码，//FIXME:标注需修复的Bug，明确责任人（可选）和截止时间（可选），便于后续跟进。1.4代码结构规范（提升可维护性）单一职责：每个类、函数仅负责一件事，避免“大而全”的类或函数，函数长度建议不超过80行，类长度不超过1000行，复杂逻辑拆分至子函数/子模块。嵌套限制：if、for、while等循环/条件语句的嵌套不超过3层，超过则拆分函数，避免嵌套过深导致代码难以理解和维护。避免冗余：遵循DRY原则（Don’tRepeatYourself），重复代码需提炼为公共函数、工具类或组件，减少代码冗余，便于后续修改维护。早返回原则：条件判断时，优先使用早返回，避免过多嵌套，提升代码可读性，如判断参数无效时直接返回，而非嵌套执行后续逻辑。1.5安全与性能规范（规避常见风险）禁止硬编码：敏感信息（如密码、API密钥、数据库地址）、固定常量（如状态码、分页大小）禁止硬编码，需存入配置文件或环境变量。输入校验：对用户输入、接口参数进行严格校验，防范SQL注入、XSS跨站脚本等安全问题，后端可使用注解校验（如@NotBlank、@NotNull）。资源管理：文件、数据库连接、网络连接等资源使用后需及时关闭，避免资源泄漏；优先使用try-with-resources（Java）、with语句（Python）等自动关闭机制。性能优化：避免过度优化，仅在性能成为瓶颈时进行优化；优先选择时间复杂度、空间复杂度较低的算法；数据库操作避免全表扫描、频繁查询，合理使用索引。1.6版本控制规范（团队协作必备）提交信息：格式统一为“类型(模块):描述”，简洁明了，说明修改目的，如feat(user):新增用户注册功能、fix(login):修复登录令牌过期bug、docs:更新代码规范文档。提交频率：保持频繁提交，每次提交仅修改一个功能或修复一个Bug，避免大量修改一次性提交，便于问题回溯和代码回滚。分支管理：遵循合理的分支策略（如Git-flow），区分开发分支（dev）、测试分支（test）、生产分支（master/main），避免直接在生产分支修改代码。二、主流编程语言核心规范（精选重点）2.1Python规范（基于PEP8）缩进：强制使用4个空格缩进，续行采用悬挂缩进，与括号、引号对齐，或额外缩进4个空格区分续行。导入规范：导入顺序为标准库→第三方库→自定义库，不同类型导入之间用空行分隔；禁止使用fromxxximport*，避免命名冲突。命名补充：包名、模块名全小写，无下划线；函数、变量用小驼峰或下划线命名（推荐下划线，如user_name）；类名用大驼峰，异常类以Error/Exception结尾。特殊规范：避免使用分号结尾；空行使用两个空行分隔类，一个空行分隔函数；字符串优先使用双引号，统一风格；不推荐使用lambda表达式替代复杂函数。2.2Java规范（基于GoogleJavaStyleGuide）缩进：使用2个空格缩进，大括号（{}）单独成行，左括号紧跟语句末尾，右括号与语句开头对齐。命名补充：包名全小写（如com.novel.user）；接口名以I开头（如IUserService），实现类以Impl结尾（如UserServiceImpl）；方法名、变量名用小驼峰。代码结构：类成员顺序为静态变量→实例变量→构造方法→普通方法；重写方法必须添加@Override注解；禁止使用finalizers（终结器）。异常处理：捕获具体异常（如NullPointerException），禁止捕获万能Exception；异常需打印日志，不吞异常；自定义业务异常需明确语义，便于排查。2.3前端规范（Vue/React通用）命名补充：组件名用大驼峰（如LoginForm），公共组件前缀加Common（如CommonTable）；组件props用短横线命名（kebab-case，如user-id）；CSS类名用短横线命名或BEM规范。组件规范：单文件组件（SFC）按template→script→style顺序编写，style添加scoped隔离样式；组件拆分合理，页面级组件放views目录，通用组件放components目录，单个组件不超过500行。逻辑规范：数据驱动视图，不直接操作DOM；复杂逻辑提炼为hooks（React）或工具函数；路由路径用短横线命名，启用路由懒加载，优化页面加载速度。请求规范：Axios统一拦截，请求添加Token，响应统一处理错误；API按模块拆分（如api/user.js），避免所有请求写在同一个文件。2.4数据库规范（通用）命名：库名、表名、字段名均为小写+下划线，如novel_db、user_info、user_id；同一模块表名加统一前缀（如用户模块user_）。表结构：主键统一用id，采用自增主键（MySQL）或雪花ID，禁用复合主键；所有表必备create_time（创建时间）、update_time（更新时间）字段，自动填充；使用is_deleted（0未删/1已删）实现软删除，替代物理删除。SQL规范：避免使用SELECT*，仅查询所需字段；禁止使用OR，优先用IN替代；大表分页优化，使用limitoffset；合理建立索引，避免过度建索引（影响插入效率），联合索引遵循最左前缀原则。三、规范落地与执行要求3.1执行原则1.一致性优先：团队内严格遵循本规范，项目内规范优先级高于通用规范，特殊场景（如历史代码兼容）可灵活调整，但需团队达成共识。2.工具辅助：使用代码检查工具（如Python的Pylint、Java的Checkstyle、前端的ESLint/Prettier）自动校验代码风格，减少人工检查成本。3.定期复盘：团队定期开展代码评审（CodeReview），重点检查规范执行情况，及时纠正不规范写法，优化规范内容。3.2禁忌清单（严格禁止）禁止使用拼音、中文或无意义命名，禁止大小写混乱。禁止代码嵌套过深（超过3层）、函数/类过于庞大。禁止硬编码敏感信息、保留注释掉的代码、冗余重复