软件代码编写规范

软件代码编写规范1.总则1.1目的为统一代码编写标准，提升代码可读性、可维护性、可复用性和安全性，降低团队协作成本，减少潜在缺陷，规范开发流程，确保项目代码质量稳定可控，特制定本规范。本规范适用于所有软件开发项目及相关开发人员，是代码编写、审查、维护的核心依据。1.2核心原则所有代码编写需遵循“可读性＞简洁性＞性能”的核心优先级（性能优化需在保证可读性的前提下进行，且需有明确的性能瓶颈证据），同时满足以下原则：可维护性：代码需清晰易懂，便于自身及其他开发人员后续修改、调试和扩展；可复用性：避免重复编码，提炼通用逻辑、工具类和组件，提升开发效率；可测试性：代码结构清晰，模块职责单一，便于编写单元测试和集成测试；一致性：团队内严格遵循统一的编码风格，减少认知成本；安全性：规避常见安全隐患，如SQL注入、XSS攻击、资源泄漏等。1.3适用范围本规范适用于技术部门所有软件开发项目，包括但不限于新建项目编码、现有项目规范统一、团队新成员培训、代码审查（CodeReview）等场景，可根据项目技术栈（如Java、Python、前端等）针对性调整细节，确保与实际开发场景匹配。2.通用基础规范2.1命名规范命名是代码可读性的基础，需遵循“见名知义、简洁规范、无歧义”原则，统一使用英文命名，禁用拼音、中文或无意义字符，具体规则如下：2.1.1变量命名采用小驼峰命名法（camelCase），使用具有描述性的名称，清晰传达变量用途，避免单个字母或无意义缩写（常见标准缩写如id、URL、API除外）。示例：userName（用户名）、totalAmount（总金额）、orderList（订单列表），禁止使用a、b、x、temp等无意义命名。2.1.2常量命名采用全大写字母+下划线分隔（UPPER_SNAKE_CASE），明确标注常量用途，避免模糊命名。示例：MAX_RETRY_COUNT（最大重试次数）、PI（圆周率）、STATUS_ENABLE（启用状态）。2.1.3函数/方法命名采用小驼峰命名法，以动词开头，清晰描述方法功能，避免过长或模糊命名，确保一眼可识别方法用途。示例：getData（获取数据）、calculateTotal（计算总额）、fetchUserInfo（查询用户信息）、login（登录）。2.1.4类/接口命名类名采用大驼峰命名法（PascalCase），以名词或名词短语为主，体现类的职责；接口名可加“I”前缀（可选，团队统一即可），同样采用大驼峰命名。示例：UserProfile（用户信息类）、DatabaseConnection（数据库连接类）、IUserService（用户服务接口）。2.1.5包/模块/文件夹命名包名、模块名、文件夹名统一采用全小写，单词间用“.”（包名）或横杠（文件夹）分隔，优先采用倒置域名+模块名的格式（后端），前端文件夹可采用小驼峰或横杠分隔，保持项目内一致。示例：com.example.user.service（后端包名）、novel-system（前端文件夹）、api/user（前端接口模块）。2.2格式规范统一的代码格式可大幅提升可读性，所有开发人员需严格遵循以下规则，可借助IDE工具（如ESLint、Prettier、Pylint）自动格式化：2.2.1缩进统一使用4个空格缩进（或2个空格，团队统一即可），禁止混合使用空格和制表符（Tab）；若必须使用Tab，需在IDE中配置为等效空格数。续行缩进需与上下文保持一致，可采用悬挂缩进提升可读性。2.2.2行长度单行代码长度控制在80-120个字符之间，特殊情况可放宽至140字符，超长行需合理分行，避免横向滚动查看，分行时需遵循语言语法规范，确保逻辑连贯。2.2.3空行与空格空行：在类与类、方法与方法、逻辑块之间添加适当空行（通常1行），区分不同功能模块，避免代码拥挤；文件末尾禁止保留空行。空格：关键字（if、for、while等）后加1个空格；运算符（=、+、-、==、&&等）两侧各加1个空格；逗号、分号后加1个空格（分号后若为行尾可省略）；括号内侧不加空格。2.2.4大括号位置左大括号不换行，与声明语句同行；右大括号单独一行，且与对应声明语句对齐。特殊场景（如单行if语句）可简化，但团队需统一标准，避免混乱。示例：publicvoidmethod(){//方法体}2.2.5文件编码所有代码文件统一采用UTF-8编码，避免中文乱码；文件命名需与内部核心类/模块名称一致，后缀名符合对应语言规范（如.java、.py、.vue）。2.3注释规范注释的核心作用是解释“为什么做”和“复杂逻辑”，而非“做了什么”，需简洁、准确、无冗余，避免过时注释和无用注释，具体规则如下：2.3.1类注释放在类声明上方，说明类的作用、职责、依赖关系、作者、版本等信息，使用块注释（/*...*/），格式统一。示例：/*用户服务类，负责用户信息管理、权限校验等功能，依赖UserMapper和RedisTemplate。author:XXX，version:1.0*/2.3.2方法注释放在方法声明上方，说明方法功能、参数（名称、类型、用途）、返回值、异常场景、边界条件等，使用块注释，可借助标签（如@param、@return、@throws）提升规范性。示例：/*根据用户ID查询用户信息。@paramuserId用户ID，不能为空；@return用户信息对象，若不存在返回null；@throwsIllegalArgumentException当userId为空时抛出*/2.3.3行注释用于解释复杂逻辑、特殊处理或临时说明，放在需解释代码的上方或右侧，使用//开头，避免每行代码都加注释，禁止冗余注释（如//循环遍历）。2.3.4特殊注释临时代码需标注//TODO:待优化（说明优化方向）或//FIXME:修复XX问题（说明问题内容）；禁止保留注释掉的代码，不再使用的代码块需直接删除，避免冗余。2.4代码结构规范单一职责：每个函数、类仅负责一项功能，避免“大而全”的代码块，单个函数代码不超过80行，单个类不超过1000行，复杂逻辑需拆分为子函数/子模块。嵌套层级：if、for、while等循环/条件语句的嵌套不超过3层，超过则拆分函数，提升可读性。早返回原则：条件判断时，尽量使用早期返回，避免过多嵌套，简化代码逻辑。避免重复：遵循DRY原则（Don'tRepeatYourself），重复逻辑需提炼为工具类、公共函数或组件，减少冗余。3.分语言专项规范3.1后端代码规范（Java/Python/Go通用）3.1.1分层开发规范（MVC架构）Controller层：仅负责接收请求、参数校验、返回响应，不编写业务逻辑；接口路径统一前缀（如/api/v1/user/*），请求方式与CRUD对应（GET查询、POST新增、PUT修改、DELETE删除）；统一响应格式（如{code:200,msg:"成功",data:{}}），配置全局异常处理。Service层：核心业务逻辑实现层，负责事务控制（如@Transactional），采用“接口+实现类”模式（如UserService+UserServiceImpl），避免业务逻辑分散。DAO/Mapper层：负责数据库操作，方法名与SQL逻辑对应（如selectById、insert），避免复杂SQL，优先使用ORM框架简化操作，防止SQL注入。模型层：Entity/Model映射数据库表，字段名与表字段一致；DTO/VO用于前后端数据传输，屏蔽无用字段，避免直接暴露数据库实体。3.1.2特殊规范Java：遵循GoogleJavaStyleGuide，包名全小写，类名大驼峰，方法名小驼峰；重写方法必须添加@Override注解；避免使用finalizers；异常捕获需具体，不使用万能catch(Exceptione)，且需记录异常日志。Python：遵循PEP8规范，缩进4个空格，导入模块按“标准库→第三方库→自定义库”顺序排列，每行仅导入一个模块；避免使用全局变量，函数参数尽量简洁，不超过5个。通用禁忌：禁用硬编码（如if(status==1)需改为定义常量STATUS_ENABLE=1）；不直接返回null，用空集合或Optional替代；事务仅加在Service层，避免嵌套事务。3.2前端代码规范（Vue/React通用）3.2.1命名规范补充组件名：采用大驼峰命名法（如LoginForm.vue），公共组件前缀统一（如CommonTable.vue）；Props命名：采用短横线分隔（kebab-case），如user-id，与模板中使用保持一致；CSS类名：采用短横线分隔（kebab-case）或BEM命名规范（如login__input--error），避免使用内联样式。3.2.2组件开发规范单文件组件（SFC）：按template→script→style顺序编写，style标签添加scoped属性隔离样式，避免样式污染。组件拆分：分为页面级组件（views目录下）和通用UI组件（components目录下），单个组件代码不超过500行，复杂组件拆分为子组件。Props校验：定义Props时指定类型、默认值和校验规则（如{userId:{type:Number,required:true}}），提升代码健壮性。生命周期：Vue3优先使用组合式API（setup），React优先使用Hooks，避免过度使用生命周期钩子，复杂逻辑提取为hooks或工具函数。3.2.3其他规范模板：使用语义化标签（如header、aside），避免嵌套过深（不超过3层），避免冗余DOM元素。请求封装：Axios统一拦截（请求添加Token、响应处理错误），API按模块拆分（如api/user.js），避免重复请求逻辑。路由：路径采用短横线分隔（如/user-center），配置路由懒加载，减少首屏加载时间。样式：优先使用预处理器（SCSS/LESS），公共样式提取到common.scss，避免使用!important覆盖样式。3.3数据库相关规范3.3.1命名规范库名、表名、字段名统一采用小写+下划线分隔，同一模块表名加统一前缀（如用户模块user_、订单模块order_），字段名见名知义（如create_time创建时间、is_deleted软删除标识）。3.3.2表结构规范主键：统一使用id，采用自增主键（MySQL）或雪花ID，禁用复合主键；必备字段：所有表添加create_time（创建时间）、update_time（更新时间），配置自动填充；软删除：使用is_deleted（0未删除/1已删除）替代物理删除，便于数据恢复；字段类型：按需选择，避免滥用varchar(255)，如手机号用char(11)，金额用decimal(10,2)。3.3.3索引与SQL规范索引：主键默认创建索引，查询频繁字段添加索引，联合索引遵循最左前缀原则，避免过度建索引（影响插入效率）；SQL：避免使用SELECT*，不用OR用IN，大表分页优化（使用limitoffset），防止全表扫描；外键：建议使用逻辑外键（代码控制关联），而非物理外键，降低表之间的耦合度。4.安全规范输入验证：对所有用户输入进行校验（如长度、格式、合法性），防止SQL注入、XSS攻击、参数篡改等；敏感信息处理：密码、API密钥、数据库连接信息等敏感内容，不硬编码在代码中，需存放在环境变量或配置文件中，加密存储；资源释放：文件、数据库连接、网络连接等资源使用后及时关闭，避免资源泄漏；权限控制：接口访问需添加权限校验，避免越权访问，敏感操作需记录操作日志。5.版本控制规范5.1提交规范提交信息需简洁明了，格式统一为“类型(模块):描述”，类型包括：feat：新增功能（如feat(user):新增用户注册功能）；fix：修复bug（如fix(order):修复订单支付失败bug）；docs：文档更新（如docs:更新接口文档）；refactor：代码重构（不改变功能，仅优化结构）；style：格式修改（不影响代码逻辑）；test：增加或修改测试用例。提交频率：避免长时间不提交，建议每完成一个小功能或修复一个bug就提交一次，便于回溯和问题定位。5.2分支规范主分支（main/master）：存放正式发布版本，禁止直接在主分支上开发；开发分支（develop）：日常开发分支，所有功能开发、bug修复均基于此分支；功能分支（feature/xxx）：基于develop分支创建，用于单个功能开发，完成后合并到develop分支；修复分支（hotfix/xxx）：基于main分支创建，用于线上bug紧急修复，完成后合并到main和develop分支。6.规范落地与优化6.1落地流程需求调研：调研团队现有编码习惯、痛点及项目技术栈特性，输出《编码规范需求说明书》；规范定制：基于本规范，结合项目特性