代码规范(一一一团队)

这个作业属于哪个课程	2301-计算机学院-软件工程
这个作业要求在哪里	团队作业—beta冲刺+事后诸葛亮
这个作业的目标	Beta阶段代码规范
团队置顶随笔	Beta冲刺置顶随笔（一一一团队）

前端代码规范

一、HTML规范

用法规范

1. 多特性分行写
   为提高可读性，组件应用时换行，按照ref、class、传入、传出顺序书写，如下：

<template>
  <scroll
    ref="scrollWrap"
    class="home-scroll-warp"
    :data="homeData"
    :pullDownRefresh="true"
    :pullUpLoad="true"
    @pullingDown="pullingDownGetNewData"
    @pullingUp="pullingUpGetMore"
  />
</template>

1. 避免重复
   避免过多重复代码，如果超过三行类似的代码，配置数据再循环遍历
2. 活用v-show，v-if

注释规范

<!-- test注释 -->
<div class="test">
  <!-- 组件注释 -->
  <gdCustomTable ref="gdCustomTable"  />
  <!-- 其他注释 -->
	<div>...</div>
</div>

二、CSS规范

用法规范

• 避免使用标签选择器。因为在 Vue 中，特别是在局部组件，使用标签选择器效率特别低，损耗性能，建议需要的情况，直接定义 class；
• 非特殊情况下，禁止使用 ID 选择器定义样式。有 JS 逻辑的情况除外；
• 避免大量的嵌套规则，控制在3级之内，对于超过4级的嵌套，考虑重写或新建子项；
• 尽量使用 scoped 关键字，约束样式生效的范围
• 可复用属性尽量抽离为页面变量，易于统一维护

书写规范

1. css声明书写

css或wxss的样式书写，应遵循父元素下的子元素，递进式的书写，谨慎处理公共样式

<view class="home-page">
    <view class="header">
        <view class="title">标题</view>
    </view>
<view>

• 反例

.home-page{}
.header{}
.title{}

• 标准

.home-page{}
.home-page .header{}
.home-page .header .title{}

注意：对于敏感的单词，例如header和title等，一定要做特别的限制要求，容易造成样式混合错乱。开发中自己视情况而定。

1. rpx和px的运用

rpx(手机的宽度是750rpx)使用属性：

• width
• height
• padding
• margin
• top，bottom，righit，left

px使用属性：

• font-size
• box-shadow
• border-radius
• border

书写顺序

先决定定位宽高显示大小，再做局部细节修饰，推荐顺序：定位属性(或显示属性，display)->宽高属性->边距属性(margin, padding)->字体，背景，颜色等，修饰属性的定义

三、JS规范

用法规范

1. 在vue-cli 脚手架使用架自带的指向 src 开发目录的 ‘@’ 符号引入文件资源
2. 使用计算属性规避 v-if 和 v-for 用在一起
3. 统一使用单引号
4. 坚持单一原则，函数内仅做该函数应该做的，尽量避免通过传入标记控制不同行为
5. 优先考虑三目运算符，但谨记不要写超过3层的三目运算符
6. 对于无用代码必须及时删除，例如：一些调试的 console 语句、无用的弃用功能代码，如在开发分支可提交打印代码，但要注意打印格式

js变量名

• 基本变量的驼峰命名

let homePage = []
let name = '小明'

• 常量名的大写或首字符大写

const AudioContext = wx.createInnerAudioContext() 
const API = {}

四、命名规范

前端文件名

以首字母小写为主的驼峰写法（默认创建时就是小写，改大写时麻烦），例如：

• homePage
  • homePage.wxml
  • homePage.wxss
  • homePage.js
  • homePage.json

class样式类命名

小写并以中线连接，例如

<view class="home-page"></view>

图片命名

图片使用img，图标使用icon

• img_功能/类型_编号
• icon_功能/类型_编号

方法命名

尽量完整英文命名，语义表达需完整清楚
按照小驼峰命名法，可使用常见动词约定
can 判断是否可执行某个动作，函数返回一个布尔值。true：可执行；false：不可执行
has 判断是否含有某个值， 函数返回一个布尔值。- true：含有此值；false：不含有此值
is： 判断是否为某个值，函数返回一个布尔值。true：为某个值；false：不为某个值
get： 获取某个之，函数返回一个非布尔值
set： 设置某个值，无返回值、返回是否设置成功或者返回链式对象 load 加载某些数据,无返回值或者返回是否加载完成的结果

后端代码规范

一、代码规范

变量命名

1. 代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。
2. 代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。
3. 类名使用UpperCamelCase风格，必须遵从驼峰形式，但以下情形例外：（领域模型的相关命名）DO / BO / DTO / VO等。
4. 方法名、参数名、成员变量、局部变量都统一使用lowerCamelCase风格，必须遵从驼峰形式。
5. 常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。
6. 抽象类命名使用Abstract或Base开头；异常类命名使用Exception结尾；测试类命名以它要测试的类的名称开始，以Test结尾。
7. 中括号是数组类型的一部分，数组定义如下：String[] args;
8. POJO类中布尔类型的变量，都不要加is，否则部分框架解析会引起序列化错误。
9. 包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式，但是类名如果有复数含义，类名可以使用复数形式。
10. 杜绝完全不规范的缩写，避免望文不知义。
11. 如果使用到了设计模式，建议在类名中体现出具体模式。
12. 接口类中的方法和属性不要加任何修饰符号（public也不要加），保持代码的简洁性，并加上有效的Javadoc注释。尽量不要在接口里定义变量，如果一定要定义变量，肯定是与接口方法相关，并且是整个应用的基础常量。

常量定义

1. 不允许出现任何魔法值（即未经定义的常量）直接出现在代码中。
2. long或者Long初始赋值时，必须使用大写的L，不能是小写的l，小写容易跟数字1混淆，造成误解。
3. 不要使用一个常量类维护所有常量，应该按常量功能进行归类，分开维护。如：缓存相关的常量放在类：CacheConsts下；系统配置相关的常量放在类：ConfigConsts下。
4. 常量的复用层次有五层：跨应用共享常量、应用内共享常量、子工程内共享常量、包内共享常量、类内共享常量。
5. 如果变量值仅在一个范围内变化用Enum类。如果还带有名称之外的延伸属性，必须使用Enum类，下面正例中的数字就是延伸信息，表示星期几。

格式规约

1. 大括号的使用约定。如果是大括号内为空，则简洁地写成{}即可，不需要换行；如果是非空代码块则：
2. 左括号和后一个字符之间不出现空格；同样，右括号和前一个字符之间也不出现空格。详见第5条下方正例提示。
3. if/for/while/switch/do等保留字与左右括号之间都必须加空格。
4. 任何运算符左右必须加一个空格。
5. 缩进采用4个空格，禁止使用tab字符。
6. 单行字符数限制不超过 120个，超出需要换行，换行时遵循如下原则：
7. 方法参数在定义和传入时，多个参数逗号后边必须加空格。
8. IDE的text file encoding设置为UTF-8; IDE中文件的换行符使用Unix格式，不要使用windows格式。 9.*【推荐】*没有必要增加若干空格来使某一行的字符与上一行的相应字符对齐。
9. 方法体内的执行语句组、变量的定义语句组、不同的业务逻辑之间或者不同的语义之间插入一个空行。相同业务逻辑和语义之间不需要插入空行。

注释规约

1. 类、类属性、类方法的注释必须使用Javadoc规范，使用/*内容/格式，不得使用//xxx方式。
2. 所有的抽象方法（包括接口中的方法）必须要用Javadoc注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。
3. 所有的类都必须添加创建者信息。
4. 方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/ */注释，注意与代码对齐。
5. 所有的枚举类型字段必须要有注释，说明每个数据项的用途。
6. 与其“半吊子”英文来注释，不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可。
7. 代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改。
8. 注释掉的代码尽量要配合说明，而不是简单的注释掉。
9. 对于注释的要求：
10. 好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担。
11. 特殊注释标记，请注明标记人与标记时间。注意及时处理这些标记，通过标记扫描，经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。

异常处理

1.不要捕获Java类库中定义的继承自RuntimeException的运行时异常类，如：IndexOutOfBoundsException / NullPointerException，这类异常由程序员预检查来规避，保证程序健壮性。

2.异常不要用来做流程控制，条件控制，因为异常的处理效率比条件分支低。

3.对大段代码进行try-catch，这是不负责任的表现。catch时请分清稳定代码和非稳定代码，稳定代码指的是无论如何不会出错的代码。对于非稳定代码的catch尽可能进行区分异常类型，再做对应的异常处理。

4.捕获异常是为了处理它，不要捕获了却什么都不处理而抛弃之，如果不想处理它，请将该异常抛给它的调用者。最外层的业务使用者，必须处理异常，将其转化为用户可以理解的内容。

5.有try块放到了事务代码中，catch异常后，如果需要回滚事务，一定要注意手动回滚事务。

6.finally块必须对资源对象、流对象进行关闭，有异常也要做try-catch。

7.不能在finally块中使用return，finally块中的return返回后方法结束执行，不会再执行try块中的return语句。

8.捕获异常与抛异常，必须是完全匹配，或者捕获异常是抛异常的父类。

9.方法的返回值可以为null，不强制返回空集合，或者空对象等，必须添加注释充分说明什么情况下会返回null值。调用方需要进行null判断防止NPE问题。

10.防止NPE，是程序员的基本修养。

11.在代码中使用“抛异常”还是“返回错误码”，对于公司外的http/api开放接口必须使用“错误码”；而应用内部推荐异常抛出；跨应用间RPC调用优先考虑使用Result方式，封装isSuccess、“错误码”、“错误简短信息”。

12.定义时区分unchecked/checked异常，避免直接使用RuntimeException抛出，更不允许抛出Exception或者Throwable，应使用有业务含义的自定义异常。推荐业界已定义过的自定义异常，如：DAOException / ServiceException等。

13.避免出现重复的代码（Don’t Repeat Yourself），即DRY原则。

控制语句

1.在一个switch块内，每个case要么通过break/return等来终止，要么注释说明程序将继续执行到哪一个case为止；在一个switch块内，都必须包含一个default语句并且放在最后，即使它什么代码也没有。

2.在if/else/for/while/do语句中必须使用大括号，即使只有一行代码，避免使用下面的形式：if (condition) statements;

3.推荐尽量少用else， if-else的方式可以改写成：

4.除常用方法（如 getXxx/isXxx）等外，不要在条件判断中执行其它复杂的语句，将复杂逻辑判断的结果赋值给一个有意义的布尔变量名，以提高可读性。

5.循环体中的语句要考量性能，以下操作尽量移至循环体外处理，如定义对象、变量、获取数据库连接，进行不必要的try-catch操作（这个try-catch是否可以移至循环体外）。

6.接口入参保护，这种场景常见的是用于做批量操作的接口。

7.方法中需要进行参数校验的场景：

• 调用频次低的方法。
• 行时间开销很大的方法，参数校验时间几乎可以忽略不计，但如果因为参数错误导致中间执行回退，或者错误，那得不偿失。
• 需要极高稳定性和可用性的方法。
• 对外提供的开放接口，不管是RPC/API/HTTP接口。
• 敏感权限入口。

8.方法中不需要参数校验的场景：

• 极有可能被循环调用的方法，不建议对参数进行校验。但在方法说明里必须注明外部参数检查。
• 底层的方法调用频度都比较高，一般不校验。毕竟是像纯净水过滤的最后一道，参数错误不太可能到底层才会暴露问题。一般DAO层与Service层都在同一个应用中，部署在同一台服务器中，所以DAO的参数校验，可以省略。
• 被声明成private只会被自己代码所调用的方法，如果能够确定调用方法的代码传入参数已经做过检查或者肯定不会有问题，此时可以不校验参数。

其他

1. 在使用正则表达式时，利用好其预编译功能，可以有效加快正则匹配速度。
2. velocity调用POJO类的属性时，建议直接使用属性名取值即可，模板引擎会自动按规范调用POJO的getXxx()，如果是boolean基本数据类型变量（boolean命名不需要加is前缀），会自动调用isXxx()方法。
3. 后台输送给页面的变量必须加$!{var}——中间的感叹号。
4. 注意 Math.random()这个方法返回是double类型，注意取值的范围 0≤x<1（能够取到零值，注意除零异常），如果想获取整数类型的随机数，不要将x放大10的若干倍然后取整，直接使用Random对象的nextInt或者nextLong方法。
5. 获取当前毫秒数System.currentTimeMillis();而不是new Date().getTime();
6. 尽量不要在vm中加入变量声明、逻辑运算符，更不要在vm模板中加入任何复杂的逻辑。
7. 任何数据结构的构造或初始化，都应指定大小，避免数据结构无限增长吃光内存。
8. 对于“明确停止使用的代码和配置”，如方法、变量、类、配置文件、动态配置属性等要坚决从程序中清理出去，避免造成过多垃圾。