首页 > 其他分享 >代码规范

代码规范

时间:2024-04-26 13:58:43浏览次数:22  
标签:功能 上线 代码 规范 注释 文档 使用

代码格式规范

  1. 缩进:使用制表符(tab)或4个空格进行缩进,确保代码布局整齐便于阅读。

  2. 空行:函数定义之间、类定义之间应有一行空行;方法或逻辑块内部,若有必要分隔,可使用一行空行。

  3. 行宽:建议单行代码长度不超过120字符,过长的表达式或字符串应合理换行。

  4. 命名:
    ○ 变量名、函数名、方法名采用小驼峰式命名(lowerCamelCase),如myVariable、doSomething()。
    ○ 常量全大写,单词间用下划线连接,如MAX_VALUE。
    ○ 类名采用大驼峰式命名(UpperCamelCase),如MyClass。
    ○ 接口名以"I"开头,遵循大驼峰式命名,如IMyInterface。
    ○ 文件名应与其中定义的主要类名一致,采用小写字母和下划线,如my_class.py。
    ○ 不得使用中英文混合的命名
    ○ 不得使用具有歧义的缩写
    ○ 不得使用魔术值(未预先定义的常量)
    ○ 禁止使用关键字或具有特殊含义的字符
    ○ vue文件、文件夹命名统一采用小驼峰
    ○ CSS命名参考BEM命名规范
    ■ 块 Block:组件的最外层父元素定义为块。
    ● 元素 Elemnt:组件内部可以是一个或多个称为元素的子元素。
    ● 修饰符 Modifier:块或元素可能具有由修饰符表示的变体。

  5. 注释:
    ○ 使用有意义的注释来解释代码的目的、逻辑或复杂算法,避免冗余和无效注释。
    ○ 对于函数、类等结构,注释应前置,描述其功能、输入、输出、异常情况及注意事项。
    ○ 使用多行注释(如/* ... */或""" ... """)对模块、类或大型函数进行概述,单行注释(如//或#)用于解释局部代码细节。
    ○ 遵循文档注释标准(如Java的Javadoc、Python的docstring),便于生成API文档。
    ○ 避免注释过多
    ○ 无用注释及时删除

  6. 代码
    ○ 所有逻辑代码均需要使用大括号,单行逻辑语句也需要使用。
    ○ 复杂代码块需要额外补充注释
    ○ switch语句必须包含break
    ○ 所有字符串统一使用utf-8
    ○ 配置参数必须保留注释及文档

  7. 时间:统一使用格式yyyy-MM-dd HH:mm:ss

编程实践规范

  1. 代码复用:提倡使用函数、类、模块等实现代码复用,避免重复代码。对于常用的功能,考虑封装成库或组件。
  2. 异常处理:明确捕获并处理可能抛出的异常,提供有用的错误信息。避免过度使用全局异常捕获,确保异常传播的合理性。
  3. 单元测试:为关键功能编写单元测试,确保代码的正确性和稳定性。测试用例应覆盖正常场景、边界条件和异常情况。
  4. 数据验证:对接收的外部输入(如用户输入、接口调用参数)进行严格的数据验证,防止因非法数据导致的程序异常。

代码版本控制

  1. 提交必须添加说明:说明信息简短、清晰,还可以通过关联需求文档、测试用例、方案文档、效果截图等方式进行补充说明。commit 信息可参考《约定式提交》文档,但不做强制要求。
  2. 提交频率:单个功能完成后提交,避免将所有修改在下班时一次性提交。当天未完成的代码在下班时统一提交,需要将无法运行的逻辑注释保证代码能够正常运行。
  3. 代码合并:如遇到较复杂的冲突需要相同人员一起评估需保留的代码。
  4. 功能分支:如果修改的代码较多或影响范围较大不适宜在主版本进行时需要添加特性分支,分支命名参考:FEATURE_FUNCTION 例:FEATURE_UserCenter
  5. 只有通过测试和产品验收的代码,才能够发起合并到主分支的 PR 请求。在这之前可以提交到自己的分支。
  6. 每次合并尽量只专注于一个功能或改动,避免多个功能耦合在一起合并,提高审查效率并降低改动风险。

注意事项

  1. 确保自己充分理解了业务和需求,需要先进行整体的方案设计;尤其是对于重要需求和核心业务,必须先跟组内同学核对方案并通过后,才能下手开发,避免重复工作。
  2. 先熟悉项目再开发,建议阅读项目文档、项目代码、接口文档、前端组件文档等。
  3. 慎重引入新的依赖或类库、或者升级版本,重大依赖变更需要和组内其他成员确认。
  4. 熟悉团队已实现的功能和代码,尽量复用,避免重复开发。
  5. 开发新功能时,确保从项目仓库拉取 最新主分支 的代码。
  6. 每个功能都要新建自己的分支进行开发,千万不要直接修改主分支的代码!注意分支名称要使用英文、足够语义化,不要和其他人的混淆。
  7. 开发时,尽量复用现有的功能、模块、类、方法、对象代码。有现成的代码,就不要再重复编写。如无法复用,可以适当通过注释说明。
  8. 开发时,遵循团队内部的研发规范,尽量参考现有项目代码的写法,尤其是不要使用和原项目不一致的格式、命名、写法,避免特立独行。
  9. 开发过程中,有任何不明确的地方,不要凭空猜测,及时去联系项目的其他成员或负责人确认。
  10. 开发过程中,注意整体时间进度的把控,先完成再优化,有风险时及时反馈。
  11. 开发时,需要格外注意对异常情况的捕获和处理。
  12. 每个分支尽量保证纯净,尽量减少每次开发和提交时改动的代码量。建议每次开分支只改一个功能、Bug 或模块,不要把多个不相关的功能写在一起,并且非必要不修改。
  13. 完成部分功能开发后,一定要自测!自测时,可以 Mock 假数据。注意一定不要在线上测试、一定不要影响线上数据!

上线规范

  1. 上线前,除了严格验证功能特性能否正常运行、并符合需求外,还要格外关注程序的:
  2. 健壮性。比如给用户友好的错误提示、输入校验。
  3. 安全性。防止越权操作、输入校验。
  4. 稳定性。尽量保证调用 100% 成功,如果有几率失败,要考虑重试或容错策略。
  5. 除非特殊情况,只有经过产品验证的功能、通过代码审核的主分支代码才允许发布上线。
  6. 除非特殊情况,尽量在工作日上线(建议周二 ~ 周四),保证上线后出了问题时能够及时修复。
  7. 上线后,一定要再次进行完整流程的测试,尤其要重点关注权限相关的功能测试。
  8. 上线后,一定要在群内及时同步上线信息,周知相关的成员,如果遇到问题第一时间反馈。
  9. 上线验证通过、并经过内部群成员确认后,可以在外部用户群发布版本更新公告。
  10. 上线后,即时更新项目的更新记录文档。
  11. 注意,上线不是终点。上线后的一段时间(至少一周内),一定要持续观察自己负责的功能是否正常运行、持续接受用户反馈、通过数据分析来观察新功能的效果,期间有任何问题都需要即时修复处理,并且准备好下一期的改进迭代。
  12. 新研发产品上线需提供完整操作及部署手册

面向对象设计规范

  1. 单一职责原则:每个类或模块应只有一个引起其变化的原因,避免类职责过多导致的复杂性和耦合度增加。
  2. 开闭原则:设计应允许扩展功能,而不修改已有代码。通过抽象、接口、继承等方式实现。
  3. 里氏替换原则:子类应可以替换其基类在程序中出现的任何地方,且不影响程序正确性。
  4. 依赖倒置原则:高层模块不应依赖低层模块,二者都应依赖于抽象。具体依赖于抽象,而非抽象依赖于具体。
  5. 接口隔离原则:尽量细化接口,使得客户端仅依赖所需的接口方法,减少无关紧要的方法对客户端的干扰。

特定语言规范
后端

  1. 多表Join不允许超过3张表
  2. 不允许使用Linq to sql
  3. 所有可能为null的逻辑需要处理异常
  4. 关键逻辑需要保留日志
  5. 避免循环调用数据库
  6. 接口参数过多时需要封装成对象
  7. 所有查询均使用Get,除特殊场景下不得使用Post处理Get请求
  8. 所有必填字段需要校验是否为空或通过[Required]处理
  9. 字符串频繁需要修改、拼接时使用StringBuilder
  10. 读写文件时必须判断目录、文件是否存在
  11. 避免使用count():count()会统计值为 NULL 的行,而 count(列名)不会统计此列为 NULL 值的行
  12. 避免使用存储过程:难以调试、扩展,没有移植性
  13. 更新数据时必须同步更新updateuser、updatetime
  14. 如果需要根据状态查询,统一由前台传入,不得在后台写死
    web
  15. 块级元素、列表、表格元素需要添加注释
  16. 优先使用语义化标签,避免页面中全是div、p、view
  17. 使用双引号而不是单引号
  18. css选择器避免使用标签名
  19. css选择器避免使用ID选择器
  20. 使用直接子选择器
  21. 尽量使用缩写熟悉,例如 font: 100%/1.6 palatino, georgia, serif;
  22. 省略0后的单位,例如 margin: 0;
  23. 使用less时嵌套层级不得超过3层
  24. 优先使用ES6+新增的语法和函数
  25. 不得直接使用undefined进行变量判断,使用typeof和"undefined"进行判断,例如 if ( typeof name === "undefined" )
  26. 打包时注意console.log等语句,使用terser自动移除
  27. Prop定义详细,必须加注释,必须加required或default
  28. 组件样式设置作用域

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文件尽量保持

标签:功能,上线,代码,规范,注释,文档,使用
From: https://www.cnblogs.com/ives/p/18159893

相关文章

  • 代码统计利器:Rust tokei 库全面介绍
    引言作为程序员,我们常常需要统计项目中的代码行数,以了解项目规模和进度。市面上有很多代码统计工具,但不少工具存在统计不准、语言支持不全、性能不佳等问题。今天给大家介绍一个Rust生态中的代码统计利器:tokei。tokei通过语法分析准确统计代码行数,目前已支持200+种语言,而且......
  • 常用的时间序列分析方法总结和代码示例
    时间序列是最流行的数据类型之一。视频,图像,像素,信号,任何有时间成分的东西都可以转化为时间序列。在本文中将在分析时间序列时使用的常见的处理方法。这些方法可以帮助你获得有关数据本身的见解,为建模做好准备并且可以得出一些初步结论。我们将分析一个气象时间序列。利用逐时ERA......
  • 为 IIncrementalGenerator 增量 Source Generator 源代码生成项目添加单元测试
    本文属于IIncrementalGenerator增量SourceGenerator源代码生成入门系列博客,本文将和大家介绍如何为源代码生成项目添加单元测试添加单元测试的作用不仅可以用来实现通用的单元测试提高质量的功能,还能用来辅助调试IIncrementalGenerator增量SourceGenerator源代码生成项......
  • 使用 ForAttributeWithMetadataName 提高 IIncrementalGenerator 增量 Source Generat
    本文将告诉大家如何使用ForAttributeWithMetadataName方法用来提高IIncrementalGenerator增量SourceGenerator源代码生成的开发效率以及提高源代码生成器的运行效率这是一个在2022的6月15才合入的新功能。原因是Roslyn团队发现了大量的源代码生成器和分析器项目都......
  • 用python写一段将指定文件夹下的子文件夹下的“.en.srt”文件复制一份,并将复制的文件
    代码:importosimportshutildefcopy_and_rename_en_srt_files(parent_directory):#遍历指定的父目录及其所有子目录forroot,dirs,filesinos.walk(parent_directory):forfileinfiles:#检查文件是否以.en.srt结尾if......
  • C++ 多级继承与多重继承:代码组织与灵活性的平衡
    C++多级继承多级继承是一种面向对象编程(OOP)特性,允许一个类从多个基类继承属性和方法。它使代码更易于组织和维护,并促进代码重用。多级继承的语法在C++中,使用:符号来指定继承关系。多级继承的语法如下:classDerivedClass:publicBaseClass1,publicBaseClass2,...{......
  • 36.mybatis-plus代码自动生成器
    很重要的功能:参考官网:https://baomidou.com/pages/779a6e/#快速入门mybatis-plus自动帮你生成pojocontroller.....东西没啥废话上代码这个依赖: <dependency><groupId>org.apache.velocity</groupId><artifactId>velocity-engine-core</artifa......
  • 代码覆盖率
    代码覆盖率(Coverage)是一种衡量软件测试质量的指标,它用于评估测试套件中的测试用例是否足够多地执行了源代码中的语句、分支、函数等。代码覆盖率通常以百分比的形式表示,表示被测试的代码占总代码的比例。代码覆盖率主要分为以下几种类型:语句覆盖(StatementCoverage):确保每个源代......
  • 36天【代码随想录算法训练营34期】第八章 贪心算法 part05( ● 435. 无重叠区间 ● 7
    435.无重叠区间classSolution:deferaseOverlapIntervals(self,intervals:List[List[int]])->int:count=0intervals.sort(key=lambdax:x[0])foriinrange(1,len(intervals)):ifintervals[i][0]<intervals[i-......
  • r语言使用rjags R2jags建立贝叶斯模型|附代码数据
    全文下载链接:http://tecdat.cn/?p=2857最近我们被客户要求撰写关于贝叶斯的研究报告,包括一些图形和统计输出。本文是通过对area,perimeter,campactness几个变量的贝叶斯建模,来查看他们对groovelength这个变量的影响,并且对比rjagsR2jags和内置贝叶斯预测函数的结果读取数据......