程序代码编写规范

程序代码编写规范1.总则1.1目的为统一代码编写标准，提高代码的可读性、可维护性、可复用性和可扩展性，降低团队协作成本，减少潜在bug，确保项目代码质量的一致性和规范性，特制定本规范。本规范适用于所有开发人员在项目开发过程中的代码编写、修改、评审及维护工作。1.2适用范围本规范适用于团队所有开发项目，包括前端、后端、移动端等各类程序代码，涵盖代码编写、注释、格式、命名、安全等各个环节，所有参与项目开发、测试、维护的人员均需严格遵守。1.3核心原则可读性优先：代码首要满足人可理解，其次满足机器可执行，避免晦涩难懂的语法和逻辑。一致性原则：同一项目、同一模块的代码，在命名、格式、注释等方面保持统一，不允许随意变更规范。简洁性原则：在保证功能完整的前提下，尽量简化代码逻辑，避免冗余代码、重复代码。安全性原则：代码编写需考虑安全风险，避免SQL注入、XSS攻击、空指针异常等常见安全问题。可维护性原则：代码结构清晰，模块划分合理，便于后续修改、扩展和问题排查。2.命名规范命名需遵循“见名知意、简洁规范”的原则，禁止使用无意义的字符、拼音缩写（特殊约定除外），统一采用对应语言的命名风格，避免混淆。2.1变量命名前端（JS/TS/Vue等）：采用小驼峰命名法（camelCase），首字母小写，后续单词首字母大写，如userName、loginTime、isValid。后端（Java/Go/Python等）：Java/Go采用小驼峰命名法，如userId、orderService；Python采用下划线命名法（snake_case），如user_id、order_service。禁止使用单字符变量（除循环变量i、j、k等约定俗成的场景外），禁止使用拼音命名（如yonghu、dingdan），禁止使用关键字、保留字作为变量名。布尔类型变量：命名需体现“是否”含义，常用前缀is、has、can、enable，如isLogin、hasPermission、canEdit。2.2函数/方法命名所有语言统一遵循“动词+名词”的命名格式，清晰表达函数/方法的功能，如getUserInfo（获取用户信息）、saveOrder（保存订单）、deleteById（根据ID删除）。前端函数：小驼峰命名法，如handleSubmit、formatDate；后端Java/Go方法：小驼峰命名法，Python方法：下划线命名法。工具类函数：可添加统一前缀，如utils.formatTime、StringUtil.isEmpty，便于区分和调用。禁止函数/方法命名过于笼统，如doSomething、handleData，需明确具体功能。2.3类/接口命名Java/Go类、接口：采用大驼峰命名法（PascalCase），首字母大写，后续单词首字母大写，如UserController、OrderService、UserVo。类命名需体现业务含义或功能，避免无意义命名，如BaseController（基础控制器）、OrderServiceImpl（订单服务实现类）。接口命名：可添加前缀I（可选，根据项目约定），如IUserService、IOrderDao，明确接口身份。前端组件命名（Vue/React）：大驼峰命名法，如UserList、LoginForm，与组件功能保持一致。2.4常量命名所有语言统一采用全大写字母，单词之间用下划线分隔（UPPER_SNAKE_CASE），如MAX_PAGE_SIZE、USER_STATUS_ACTIVE、BASE_URL。常量需集中管理，避免分散定义，如Java中放在常量类（Constant）中，Python中放在单独的常量模块中。禁止使用魔法数字、魔法字符串，所有固定值均需定义为常量，如禁止直接写10（代表每页条数），需定义为MAX_PAGE_SIZE=10。2.5其他命名包/模块命名：采用小写字母，单词之间用下划线或点分隔（根据语言约定），如com.example.user、utils.tools、views.home。文件命名：与类/组件/模块命名保持一致，如UserController.java、user_service.py、LoginForm.vue，禁止乱命名（如test1.js、newfile.java）。数据库相关：表名采用下划线命名法（全小写），如user_info、order_detail；字段名采用下划线命名法，与变量名对应，如user_id、user_name。3.代码格式规范代码格式需统一，避免因格式混乱影响可读性，优先使用项目统一的格式化工具（如Prettier、ESLint、IDEA格式化功能），手动调整需遵循以下规范。3.1缩进统一使用4个空格缩进（禁止使用Tab缩进），确保不同编辑器、不同环境下显示一致。代码块（如if、for、while、函数体、类体）需缩进一层，逻辑结束后恢复缩进，如：示例（Java）：3.2换行每个语句单独一行，禁止多个语句写在同一行，如禁止inta=1;intb=2;，需分开写为inta=1;和intb=2;。函数/方法的左大括号{单独占一行，右大括号}单独占一行，与函数/方法名、代码块逻辑对齐，如：if、for、while等关键字后，左大括号{前需加空格，且关键字与条件表达式之间加空格，如if(condition){而非if(condition){。过长代码（超过80-120个字符，根据项目约定）需换行，换行时优先在逗号、运算符后换行，换行后缩进对齐，如：3.3空格运算符（+、-、*、/、=、==、!=、<、>等）前后各加一个空格，如inta=1+2;而非inta=1+2;。逗号（,）、分号（;）后加一个空格，逗号前不加空格，如List<String>list=newArrayList<>(Arrays.asList("a","b","c"));。括号（()、[]、{}）内部前后不加空格，如getUserById(123)而非getUserById(123)，List<User>list=newArrayList<>();而非List<User>list=newArrayList<>();。函数/方法参数之间，逗号后加一个空格，如getUserInfo(userId,userName,age)而非getUserInfo(userId,userName,age)。注释符号（//、/*）与注释内容之间加一个空格，如//这是单行注释而非//这是单行注释。3.4空行类的成员变量与方法之间、方法与方法之间，加一个空行，区分不同逻辑模块。方法内部，不同逻辑块之间加一个空行，如变量定义与业务逻辑之间、条件判断与循环之间。文件开头、结尾禁止多余空行，代码中禁止连续多个空行（最多一个空行）。import语句（Java）、require/import（前端）集中放在文件顶部，之间不加空行，与类定义之间加一个空行。4.注释规范注释是代码的补充说明，目的是帮助开发人员理解代码逻辑，减少维护成本。注释需简洁、准确、完整，避免冗余、错误的注释，遵循“必要即注释”的原则。4.1单行注释使用//注释，适用于单个语句、局部逻辑的说明，注释内容位于代码行上方或右侧（右侧注释需与代码保持足够间距）。示例：禁止注释显而易见的代码，如//定义变量a，inta=1;此类注释无意义。4.2多行注释使用/*...*/或/**...*/（Java文档注释），适用于类、接口、函数/方法的说明，以及复杂逻辑块的详细解释。类/接口注释：位于类/接口定义上方，说明类的功能、作者、创建时间、修改记录等（根据项目约定）。函数/方法注释：位于方法定义上方，说明方法的功能、参数含义、返回值、异常信息等，示例（Java）：复杂逻辑注释：对难以理解的逻辑块，添加多行注释，说明逻辑思路、设计意图，便于后续维护。4.3注释注意事项注释需与代码同步更新，禁止代码修改后注释未更新，导致注释与代码不一致。禁止使用拼音、乱码、无意义字符作为注释内容，注释语言统一使用中文（特殊场景可使用英文）。禁止注释掉代码（调试除外），无用代码需直接删除，避免冗余。注释需简洁明了，避免冗长，重点说明“为什么这么写”，而非“写了什么”（代码本身已表达“写了什么”）。5.代码逻辑规范5.1代码简洁性避免冗余代码：禁止重复编写相同的逻辑，重复逻辑需提取为函数/方法、工具类，便于复用和维护。简化条件判断：多个条件判断可合并简化，避免嵌套过深（建议嵌套不超过3层），如：不推荐：if(a){if(b){if(c){...}}}推荐：if(a&&b&&c){...}禁止无用代码：删除未使用的变量、函数、导入语句，避免占用资源和影响可读性。5.2异常处理所有可能出现异常的代码（如IO操作、数据库操作、网络请求），必须添加异常处理，禁止直接抛出未捕获的异常。异常处理需明确，避免捕获所有异常（如catch(Exceptione){...}），需针对性捕获具体异常，如catch(NullPointerExceptione)、catch(SQLExceptione)。异常信息需记录日志（如打印异常堆栈），便于问题排查，禁止空catch（catch后不做任何处理）。自定义异常：业务相关的异常，可定义自定义异常类，统一异常处理逻辑，提高代码规范性。5.3安全性规范防止SQL注入：后端数据库操作，禁止拼接SQL语句，需使用参数化查询（如MyBatis的#{}、JDBC的PreparedStatement）。防止XSS攻击：前端输入内容需进行过滤、转义，避免恶意脚本注入；后端接收前端参数时，需进行校验和转义。空指针防护：对可能为null的变量、对象，需进行非空判断，避免空指针异常，如if(user!=null&&user.getName()!=null)。密码安全：密码需加密存储（如使用MD5、SHA256等加密算法），禁止明文存储；传输过程中需使用HTTPS加密。权限控制：敏感接口、敏感操作需添加权限校验，确保只有授权用户才能访问。5.4可扩展性代码模块化：将功能拆分为独立的模块、类、函数，降低模块间的耦合度，提高可复用性和可扩展性。接口化编程：后端服务优先定义接口，再实现接口，便于后续替换实现类、扩展功能。预留扩展接口：对于可能后续扩展的功能，预留接口或配置项，避免后续修改大量代码。避免硬编码：所有可变配置（如接口地址、超时时间、常量值），需放在配置文件中，便于动态修改，禁止硬编码在代码中。6.不同语言补充规范6.1Java语言类的访问修饰符：明确类、方法、变量的访问修饰符（public、private、protected、default），避免滥用public，优先使用private，按需暴露接口。封装性：成员变量私有化，通过getter/setter方法访问，禁止直接访问成员变量。异常处理：使用try-catch-finally或try-with-resources（JDK7+）处理异常，资源（如流、连接）需及时关闭。集合使用：指定集合泛型，避免使用非泛型集合（如List而非List）；根据场景选择合适的集合，如查询频繁用HashMap，有序用TreeMap。6.2前端（JS/TS/Vue/React）变量声明：优先使用let、const，禁止使用var，避免变量提升导致的问题；const用于常量，let用于可变变量。箭头函数：优先使用箭头函数简化代码，尤其是回调函数、匿名函数，提高可读性。Vue规范：组件props需定义类型、默认值、校验规则；模板中禁止写复杂逻辑，复杂逻辑提取到computed、methods中；生命周期函数使用规范，避免滥用beforeCreate、created。React规范：组件拆分合理，单一组件只负责一个功能；使用hooks规范（如useState、useEffect），避免hooks使用违规（如在条件判断中使用hooks）。6.3Python语言缩进严格：Python依赖缩进区分代码块，必须严格遵循4个空格缩进，禁止混合Tab和空格。导入规范：导入模块需按“标准库→第三方库→自定义库”的顺序，每组之间加一个空行；禁止导入未使用的模块。函数/类定义：函数、类定义后需加文档字符串（docstring），说明功能、参数、返回值。代码长度：每行代码不超过80个字符，过长代码需换行；避免一行写多个语句。7.代码评审规范7.1评审原则代码评审是保证代码质量的重要环节，所有代码提交前（或合并前），需经过至少1名团队成员评审，评审通过后方可提交/合并。7.2评审内容规范符合性：代码是否符合本规范（命名、格式、注释等）。逻辑正确性：代码逻辑是否正确，是否实现预期功能，是否存在bug。安全性：是否存在安全隐患（如SQL注入、XSS攻击、空指针等）。可读性、可维护性：代码是否易理解，结构是否清晰，是否存在冗余