代码格式规范
-
缩进:使用制表符(tab)或4个空格进行缩进,确保代码布局整齐便于阅读。
-
空行:函数定义之间、类定义之间应有一行空行;方法或逻辑块内部,若有必要分隔,可使用一行空行。
-
行宽:建议单行代码长度不超过120字符,过长的表达式或字符串应合理换行。
-
命名:
○ 变量名、函数名、方法名采用小驼峰式命名(lowerCamelCase),如myVariable、doSomething()。
○ 常量全大写,单词间用下划线连接,如MAX_VALUE。
○ 类名采用大驼峰式命名(UpperCamelCase),如MyClass。
○ 接口名以"I"开头,遵循大驼峰式命名,如IMyInterface。
○ 文件名应与其中定义的主要类名一致,采用小写字母和下划线,如my_class.py。
○ 不得使用中英文混合的命名
○ 不得使用具有歧义的缩写
○ 不得使用魔术值(未预先定义的常量)
○ 禁止使用关键字或具有特殊含义的字符
○ vue文件、文件夹命名统一采用小驼峰
○ CSS命名参考BEM命名规范
■ 块 Block:组件的最外层父元素定义为块。
● 元素 Elemnt:组件内部可以是一个或多个称为元素的子元素。
● 修饰符 Modifier:块或元素可能具有由修饰符表示的变体。 -
注释:
○ 使用有意义的注释来解释代码的目的、逻辑或复杂算法,避免冗余和无效注释。
○ 对于函数、类等结构,注释应前置,描述其功能、输入、输出、异常情况及注意事项。
○ 使用多行注释(如/* ... */或""" ... """)对模块、类或大型函数进行概述,单行注释(如//或#)用于解释局部代码细节。
○ 遵循文档注释标准(如Java的Javadoc、Python的docstring),便于生成API文档。
○ 避免注释过多
○ 无用注释及时删除 -
代码
○ 所有逻辑代码均需要使用大括号,单行逻辑语句也需要使用。
○ 复杂代码块需要额外补充注释
○ switch语句必须包含break
○ 所有字符串统一使用utf-8
○ 配置参数必须保留注释及文档 -
时间:统一使用格式yyyy-MM-dd HH:mm:ss
编程实践规范
- 代码复用:提倡使用函数、类、模块等实现代码复用,避免重复代码。对于常用的功能,考虑封装成库或组件。
- 异常处理:明确捕获并处理可能抛出的异常,提供有用的错误信息。避免过度使用全局异常捕获,确保异常传播的合理性。
- 单元测试:为关键功能编写单元测试,确保代码的正确性和稳定性。测试用例应覆盖正常场景、边界条件和异常情况。
- 数据验证:对接收的外部输入(如用户输入、接口调用参数)进行严格的数据验证,防止因非法数据导致的程序异常。
代码版本控制
- 提交必须添加说明:说明信息简短、清晰,还可以通过关联需求文档、测试用例、方案文档、效果截图等方式进行补充说明。commit 信息可参考《约定式提交》文档,但不做强制要求。
- 提交频率:单个功能完成后提交,避免将所有修改在下班时一次性提交。当天未完成的代码在下班时统一提交,需要将无法运行的逻辑注释保证代码能够正常运行。
- 代码合并:如遇到较复杂的冲突需要相同人员一起评估需保留的代码。
- 功能分支:如果修改的代码较多或影响范围较大不适宜在主版本进行时需要添加特性分支,分支命名参考:FEATURE_FUNCTION 例:FEATURE_UserCenter
- 只有通过测试和产品验收的代码,才能够发起合并到主分支的 PR 请求。在这之前可以提交到自己的分支。
- 每次合并尽量只专注于一个功能或改动,避免多个功能耦合在一起合并,提高审查效率并降低改动风险。
注意事项
- 确保自己充分理解了业务和需求,需要先进行整体的方案设计;尤其是对于重要需求和核心业务,必须先跟组内同学核对方案并通过后,才能下手开发,避免重复工作。
- 先熟悉项目再开发,建议阅读项目文档、项目代码、接口文档、前端组件文档等。
- 慎重引入新的依赖或类库、或者升级版本,重大依赖变更需要和组内其他成员确认。
- 熟悉团队已实现的功能和代码,尽量复用,避免重复开发。
- 开发新功能时,确保从项目仓库拉取 最新主分支 的代码。
- 每个功能都要新建自己的分支进行开发,千万不要直接修改主分支的代码!注意分支名称要使用英文、足够语义化,不要和其他人的混淆。
- 开发时,尽量复用现有的功能、模块、类、方法、对象代码。有现成的代码,就不要再重复编写。如无法复用,可以适当通过注释说明。
- 开发时,遵循团队内部的研发规范,尽量参考现有项目代码的写法,尤其是不要使用和原项目不一致的格式、命名、写法,避免特立独行。
- 开发过程中,有任何不明确的地方,不要凭空猜测,及时去联系项目的其他成员或负责人确认。
- 开发过程中,注意整体时间进度的把控,先完成再优化,有风险时及时反馈。
- 开发时,需要格外注意对异常情况的捕获和处理。
- 每个分支尽量保证纯净,尽量减少每次开发和提交时改动的代码量。建议每次开分支只改一个功能、Bug 或模块,不要把多个不相关的功能写在一起,并且非必要不修改。
- 完成部分功能开发后,一定要自测!自测时,可以 Mock 假数据。注意一定不要在线上测试、一定不要影响线上数据!
上线规范
- 上线前,除了严格验证功能特性能否正常运行、并符合需求外,还要格外关注程序的:
- 健壮性。比如给用户友好的错误提示、输入校验。
- 安全性。防止越权操作、输入校验。
- 稳定性。尽量保证调用 100% 成功,如果有几率失败,要考虑重试或容错策略。
- 除非特殊情况,只有经过产品验证的功能、通过代码审核的主分支代码才允许发布上线。
- 除非特殊情况,尽量在工作日上线(建议周二 ~ 周四),保证上线后出了问题时能够及时修复。
- 上线后,一定要再次进行完整流程的测试,尤其要重点关注权限相关的功能测试。
- 上线后,一定要在群内及时同步上线信息,周知相关的成员,如果遇到问题第一时间反馈。
- 上线验证通过、并经过内部群成员确认后,可以在外部用户群发布版本更新公告。
- 上线后,即时更新项目的更新记录文档。
- 注意,上线不是终点。上线后的一段时间(至少一周内),一定要持续观察自己负责的功能是否正常运行、持续接受用户反馈、通过数据分析来观察新功能的效果,期间有任何问题都需要即时修复处理,并且准备好下一期的改进迭代。
- 新研发产品上线需提供完整操作及部署手册
面向对象设计规范
- 单一职责原则:每个类或模块应只有一个引起其变化的原因,避免类职责过多导致的复杂性和耦合度增加。
- 开闭原则:设计应允许扩展功能,而不修改已有代码。通过抽象、接口、继承等方式实现。
- 里氏替换原则:子类应可以替换其基类在程序中出现的任何地方,且不影响程序正确性。
- 依赖倒置原则:高层模块不应依赖低层模块,二者都应依赖于抽象。具体依赖于抽象,而非抽象依赖于具体。
- 接口隔离原则:尽量细化接口,使得客户端仅依赖所需的接口方法,减少无关紧要的方法对客户端的干扰。
特定语言规范
后端
- 多表Join不允许超过3张表
- 不允许使用Linq to sql
- 所有可能为null的逻辑需要处理异常
- 关键逻辑需要保留日志
- 避免循环调用数据库
- 接口参数过多时需要封装成对象
- 所有查询均使用Get,除特殊场景下不得使用Post处理Get请求
- 所有必填字段需要校验是否为空或通过[Required]处理
- 字符串频繁需要修改、拼接时使用StringBuilder
- 读写文件时必须判断目录、文件是否存在
- 避免使用count():count()会统计值为 NULL 的行,而 count(列名)不会统计此列为 NULL 值的行
- 避免使用存储过程:难以调试、扩展,没有移植性
- 更新数据时必须同步更新updateuser、updatetime
- 如果需要根据状态查询,统一由前台传入,不得在后台写死
web - 块级元素、列表、表格元素需要添加注释
- 优先使用语义化标签,避免页面中全是div、p、view
- 使用双引号而不是单引号
- css选择器避免使用标签名
- css选择器避免使用ID选择器
- 使用直接子选择器
- 尽量使用缩写熟悉,例如 font: 100%/1.6 palatino, georgia, serif;
- 省略0后的单位,例如 margin: 0;
- 使用less时嵌套层级不得超过3层
- 优先使用ES6+新增的语法和函数
- 不得直接使用undefined进行变量判断,使用typeof和"undefined"进行判断,例如 if ( typeof name === "undefined" )
- 打包时注意console.log等语句,使用terser自动移除
- Prop定义详细,必须加注释,必须加required或default
- 组件样式设置作用域
Vue3
src推荐代码结构:
├─api
│ ├─barcodeCenter
│ └─system
├─assets
│ ├─css
│ │ └─pages
│ │ └─barcodeCenter
│ ├─fonts
│ │ ├─dingFont
│ │ ├─operate
│ │ └─system
│ └─img
│ └─login
├─components
│ ├─element-plus
│ └─layout
├─layout
├─pages
│ ├─basicData
│ │ └─factory
│ ├─home
│ └─system
│ └─user
├─router
├─stores
├─utils
│ └─table
└─views
├─barcodeCenter
├─basicData
│ └─factory
└─system
└─drag
api目录:存放所有api请求地址,可根据功能模块建立文件夹区分
assets目录:存放静态文件,css等样式文件、字体文件、图片
components目录:通用组件目录
layout目录:布局页面
pages目录:页面封装的功能组件,可根据功能模块划分文件夹
router目录:路由相关文件
stores目录:存放状态管理(尽量减少在这里直接请求api)
utils目录:通用js方法
views目录:功能页面,可根据模块划分文件夹
.vue文件尽量保持<script><style>标签的顺序,单页面里面的样式代码不要过多,需要多的可以维护到assets下的css目录下
根据实际使用的编程语言,参照其官方或社区推荐的最佳实践和编码规范,如《Google Python Style Guide》、《Java Code Conventions》、《C# Coding Conventions》、《JavaScript Style Guide and Coding Conventions》等,结合上述通用规范,形成具体的语言特定规范。
结语
代码规范并非一成不变,随着技术发展和团队需求的变化,应适时对其进行更新和完善。每位开发者都有责任遵循并推广代码规范,通过持续的代码审查、自动化工具检查等方式,共同营造良好的代码文化,提升项目整体质量和开发效率。