程序代码规范范本

程序代码规范范本1.总则1.1目的为统一代码编写标准，提高代码可读性、可维护性、可扩展性，降低团队协作成本，减少潜在bug，确保项目代码质量稳定，特制定本规范。本规范适用于项目所有开发人员、测试人员及相关协作人员，所有代码编写、评审、修改均需严格遵循。1.2适用范围本规范适用于项目中所有程序代码（包括前端、后端、脚本、配置文件等），涵盖代码编写、命名、注释、格式、异常处理、安全等各个环节，无论使用何种开发语言，均需结合语言特性遵循本规范核心要求。1.3核心原则可读性优先：代码首要目标是让人看懂，其次是运行正常，避免晦涩难懂的写法；一致性原则：同类型代码、同一场景，需保持命名、格式、注释的统一；简洁性原则：在保证功能完整的前提下，简化代码逻辑，避免冗余、重复代码；可维护性原则：代码需便于后续修改、调试和扩展，避免硬编码、耦合度过高；安全性原则：需考虑边界条件、异常场景，防范常见安全风险（如注入、跨站、权限泄露等）。2.通用代码规范2.1代码格式规范2.1.1缩进统一使用4个空格作为缩进（禁止使用Tab缩进），确保不同编辑器、不同环境下代码显示一致。嵌套代码需严格按层级缩进，每一层嵌套增加一次缩进，避免缩进混乱。示例（以Java为例）：java

//正确

publicvoidtestMethod(){

if(condition){

System.out.println("正确缩进");

}

}

//错误（混合Tab和空格）

publicvoidtestMethod(){

if(condition){

System.out.println("错误缩进");

}

}2.1.2换行每个独立语句占一行，禁止多个语句写在同一行；括号（{}、()、[]）的换行遵循“左括号不换行，右括号单独换行”原则（特殊场景除外，如短语句简写）；逗号（,）、分号（;）后需换行（分号为语句结束标志，逗号用于分隔列表项，换行后对齐层级）；过长语句（建议单行长不超过120个字符）需换行拆分，拆分处优先在运算符、逗号后，确保拆分后逻辑清晰，对齐合理。2.1.3空格使用运算符（+、-、*、/、=、==、!=、&&、||等）前后各加1个空格；括号（()、[]）前后不加空格，括号内内容与括号之间不加空格；逗号（,）、分号（;）后加1个空格，前面不加空格；方法参数列表中，参数之间加1个空格，参数与括号之间不加空格；类、方法、变量的定义中，修饰符（public、private、static等）之间加1个空格，修饰符与名称之间加1个空格。示例（以Python为例）：python

#正确

a=10+20

ifa>20andb<30:

print(a,b)

deftest_func(param1,param2):

returnparam1*param2

#错误

a=10+20

ifa>20&&b<30:

print(a,b)

deftest_func(param1,param2):

returnparam1*param22.2命名规范命名需遵循“见名知意、简洁明了”原则，禁止使用无意义的字母（如a、b、c）、数字组合作为名称，禁止使用中文、拼音（特殊场景除外，如业务专属名词拼音已约定）。2.2.1类命名采用帕斯卡命名法（PascalCase）：首字母大写，后续每个单词首字母均大写，无下划线；命名需体现类的功能或用途，避免模糊命名（如BaseClass、UtilClass需结合场景补充具体含义）；抽象类命名以Abstract开头，接口命名以I开头（如AbstractUserService、IUserDao）。示例：UserController、OrderService、AbstractBaseMapper、IUserRepository2.2.2方法命名采用驼峰命名法（camelCase）：首字母小写，后续每个单词首字母大写，无下划线；命名需体现方法的动作和用途，动词开头，搭配名词（如getUser、addOrder、updateStatus）；查询类方法：以get、find、select开头（如getUserById、findOrderList）；新增类方法：以add、create、insert开头（如addUser、createOrder）；修改类方法：以update、modify开头（如updateUserInfo、modifyOrderStatus）；删除类方法：以delete、remove开头（如deleteUser、removeOrder）；布尔型方法：以is、has、exists开头（如isValid、hasPermission、existsUser）。2.2.3变量命名采用驼峰命名法（camelCase）：首字母小写，后续每个单词首字母大写，无下划线；局部变量、成员变量：命名简洁，体现变量含义（如userId、orderNo、userName）；常量命名：采用全大写，单词之间用下划线分隔（如MAX_PAGE_SIZE、USER_STATUS_ACTIVE）；数组、集合变量：建议以复数形式命名（如userList、orderArray），或前缀加list、array（如listUser、arrayOrder）；禁止使用关键字、保留字作为变量名（如int、class、for、if等）。2.2.4其他命名包命名：采用全小写，单词之间用点分隔，体现项目层级（如ject.controller、ject.service）；常量类命名：以Constant结尾（如UserConstant、OrderConstant）；工具类命名：以Util结尾（如DateUtil、StringUtil）；配置文件命名：全小写，单词之间用横线分隔（如application-dev.yml、logback-spring.xml）。2.3注释规范注释的目的是解释代码“为什么做”“做什么”，而非“怎么做”（代码本身应清晰体现“怎么做”），注释需简洁、准确、完整，避免冗余、错误的注释，随代码修改同步更新注释。2.3.1类注释每个类顶部必须添加注释，说明类的功能、作者、创建时间、修改记录（可选），采用块注释（/**...*/），格式统一。示例（以Java为例）：java

/**

*用户控制器

*负责处理用户相关的HTTP请求，包括用户注册、登录、信息查询与修改

*@author开发人员姓名

*@date2026-03-23

*@version1.0

*/

@RestController

@RequestMapping("/user")

publicclassUserController{

//类内容

}2.3.2方法注释每个公共方法（public）必须添加注释，说明方法的功能、参数含义、返回值含义、异常说明（可选），采用块注释，参数和返回值需明确标注。示例（以Java为例）：java

/**

*根据用户ID查询用户信息

*@paramuserId用户ID（必填，格式为数字字符串，长度不超过10位）

*@returnUser用户实体类，包含用户ID、用户名、手机号等信息

*@throwsIllegalArgumentException当userId为空或格式错误时抛出

*/

publicUsergetUserById(StringuserId){

if(userId==null||!userId.matches("\\d{1,10}")){

thrownewIllegalArgumentException("用户ID格式错误");

}

//方法逻辑

returnuserDao.selectById(userId);

}2.3.3代码行注释针对复杂逻辑、关键步骤、不易理解的代码，需添加行注释（//...），注释位于代码行上方或右侧，与代码保持对齐；禁止对简单、显而易见的代码添加注释（如//定义变量a、//循环10次）；注释需简洁，避免一行注释过长，超过80字符可拆分多行。示例（以Python为例）：python

#计算用户总积分（积分=基础积分+额外奖励-扣除积分）

total_score=base_score+extra_reward-deduct_score

#若积分小于0，重置为0（避免负积分）

iftotal_score<0:

total_score=02.3.4注释禁忌禁止注释掉无用代码（无用代码直接删除，如需保留可通过版本控制工具回溯）；禁止使用模糊、错误的注释（如//这里有问题、//不知道怎么写）；禁止注释与代码不一致（代码修改后，需同步修改对应注释）；禁止使用中文拼音注释（如//yonghuid，应改为//用户ID）。3.语言专属规范3.1Java代码规范包导入：仅导入必要的包，禁止导入未使用的包；相同层级的包按字母顺序排列，不同层级的包按层级顺序排列；类修饰符：类的访问修饰符需明确（public、private、protected），避免默认修饰符；成员变量：优先使用private修饰，通过getter/setter方法访问，禁止直接暴露成员变量；异常处理：禁止捕获异常后不做任何处理（空catch块），需打印异常信息或进行相应处理；异常捕获需精准，避免捕获Exception所有异常；代码冗余：禁止重复代码，相同逻辑可提取为方法或工具类；避免过多嵌套（建议嵌套不超过3层）；常量：常量需定义在类顶部，或单独的常量类中，禁止在方法内部定义常量；集合：使用泛型定义集合（如List<User>userList=newArrayList<>()），禁止使用无泛型集合；try-catch：try块中仅包含可能抛出异常的代码，避免将无关代码放入try块。3.2Python代码规范编码格式：统一使用UTF-8编码，文件开头添加编码声明（#-*-coding:utf-8-*-）；缩进：严格遵循4个空格缩进，禁止混合Tab和空格；导入规范：导入顺序为“标准库->第三方库->自定义库”，同一类别的导入按字母顺序排列，导入之间用空行分隔；函数/类：函数、类之间用2个空行分隔，函数内部不同逻辑块之间用1个空行分隔；变量：禁止使用全局变量（特殊场景除外），局部变量作用域尽可能小；布尔判断：避免使用ifx==True/False，直接使用ifx或ifnotx；列表推导式：简单逻辑可使用列表推导式，复杂逻辑建议拆分，避免推导式过长；注释：类、函数注释采用文档字符串（docstring），使用三引号（"""..."""），行注释使用//。3.3前端代码规范（JS/HTML/CSS）3.3.1JavaScript规范命名：变量、方法采用驼峰命名，常量全大写下划线分隔，类采用帕斯卡命名；变量声明：优先使用let、const，禁止使用var（避免变量提升带来的问题）；const用于不可修改的变量，let用于可修改的变量；箭头函数：简单函数可使用箭头函数简化，复杂函数（如需要this）慎用；对象/数组：对象字面量简洁写法，避免冗余（如{name:name}可简写为{name}）；数组初始化优先使用[]，禁止使用newArray()；异常处理：异步操作（Promise、async/await）需捕获异常，避免未处理的reject；代码冗余：避免重复代码，可提取为工具函数、组件；禁止嵌套过深（建议不超过3层）。3.3.2HTML规范文档结构：每个HTML文件需包含完整的DOCTYPE、html、head、body标签，DOCTYPE声明位于文件最顶部；标签规范：标签名全小写，闭合标签必须闭合（如<div></div>），自闭合标签无需添加闭合符号（如<img/>可简写为<img>）；属性规范：属性名全小写，属性值必须加引号（优先使用双引号）；避免使用废弃属性（如align、bgcolor）；语义化：优先使用语义化标签（如<header>、<nav>、<main>、<footer>），避免过度使用<div>；注释：HTML注释需简洁，说明标签用途或结构，避免过多注释；注释格式为<!--注释内容-->。3.3.3CSS规范命名：类名采用连字符（kebab-case），全小写，体现样式用途（如.user-card、.btn-primary）；禁止使用id作为样式选择器（id用于唯一标识，优先用于JS操作）；格式：每个选择器单独占一行，属性名和属性值之间用冒号加1个空格，属性值后加分号；多个属性按“布局->盒模型->样式->其他”顺序排列；冗余：避免重复样式，可提取公共样式（如.common-btn）；禁止使用!important（特殊场景除外，需标注原因）；兼容性：考虑浏览器兼容性，必要时添加前缀（如-webkit-、-moz-）；注释：样式块顶部添加注释，说明样式用途（如/*用户卡片样式*/），复杂样式添加行注释。4.异常处理规范4.1异常处理原则提前预防：在代码执行前，对输入参数、边界条件进行校验，避免异常发生；精准捕获：捕获异常时，优先捕获具体异常（如NullPointerException、IllegalArgumentException），避免捕获所有Exception；妥善处理：捕获异常后，需进行相应处理（如打印异常日志、返回错误信息、回滚事务），禁止空catch块；异常传递：异常需合理传递，避免随意吞掉异常，也避免过度抛出异常；日志记录：异常发生时，需记录详细的异常信息（如异常类型、异常信息、堆栈信息、发生时间），便于排查问题。4.2异常处理示例（Java）java

/**

*提交订单

*@paramorder订单信息

*@return提交结果

*/

publicResultsubmitOrder(Orderorder){

try{

//参数校验（提前预防）

if(order==null){

returnResult.fail("订单信息不能为空");

}

if(order.getUserId()==null||order.getUserId().isEmpty()){

returnResult.fail("用户ID不能为空");

}

//业务逻辑

orderService.save(order);

returnResult.success("提交成功");

}catch(IllegalArgumentExceptione){

//捕获具体异常，打印日志

log.error("订单提交参数错误：{}",e.getMessage(),e);

returnResult.fail("参数错误："+e.getMessage());

}catch(Exceptione){

//捕获其他未预料到的异常，记录详细日志

log.error("订单提交失败，订单信息：{}，异常信息：{}",JSON.toJSONString(order),e.getMessage(),e);

returnResult.fail("系统异常，请稍后重试");

}

}5.安全规范输入校验：所有用户输入（如表单提交、接口参数）必须进行校验，包括格式、长度、范围、合法性，防范注入攻击（SQL注入、XSS注入等）；权限控制：接口、页面需进行权限校验，禁止未授权访问；敏感操作（如修改密码、删除数据）需二次校验；敏感数据：敏感数据（如密码、手机号、身份证号）需加密存储（如密码使用MD5、SHA256加密），禁止明文存储；