字节乱动--团队作业六:代码规范
字节乱动--团队作业六:代码规范
| 这个作业属于哪个课程 | 2021春软件工程实践|S班 |
|---|---|
| 这个作业要求在哪里 | 团队作业六——beta冲刺+事后诸葛亮 |
| 团队名称 | 字节乱动 |
| 这个作业的目标 | 记录代码规范 |
| 其他参考文献 | 无 |
| 汇总博客 | beta冲刺+事后诸葛亮博客汇总 |
后端规范编程规范
-
格式规约：
-
缩进：采用4个空格
说明：如果使用tab缩进，必须设置1个tab为4个空格。IDEA设置tab为4个空格时，请勿勾选Use tab character；而在eclipse中，必须勾选insert spaces for tabs。
-
每行最多字符数：单行字符数限制不超过 120个，超出需要换行。
正例： StringBuffer sb = new StringBuffer(); //超过120个字符的情况下，换行缩进4个空格，并且方法前的点符号一起换行 sb.append("zi").append("xin")... .append("huang")... .append("huang")... .append("huang"); 反例： StringBuffer sb = new StringBuffer(); //超过120个字符的情况下，不要在括号前换行 sb.append("zi").append("xin")...append ("huang"); //参数很多的方法调用可能超过120个字符，不要在逗号前换行 method(args1, args2, args3, ... , argsX);-
函数最大行数：函数代码不超过80行。
-
空行规则：方法体内的执行语句组、变量的定义语句组、不同的业务逻辑之间或者不同的语义之间插入一个空行。相同业务逻辑和语义之间不需要插入空行。
-
操作符前后空格: 任何运算符左右必须加一个空格。
说明：运算符包括赋值运算符=、逻辑运算符&&、加减乘除符号、三目运行符等。
- 大括号的使用约定。如果是大括号内为空，则简洁地写成{}即可。
-
-
注释规约：
- 类、类属性、类方法的注释必须使用Javadoc规范，使用/**内容*/格式，不得使用//xxx方式。
- 所有的抽象方法（包括接口中的方法）必须要用Javadoc注释、除了返回值、参数，还必须指出该方法做什么事情，实现什么功能。
- 所有的类都必须添加创建者信息。
- 方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐。
-
所有的枚举类型字段必须要有注释，说明每个数据项的用途。
-
命名规约：
-
代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。
反例： _name / __name / $Object / name_ / name$ / Object$ -
代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。
反例： DaZhePromotion [打折] / getPingfenByName() [评分] / int某变量 = 3 正例： alibaba / taobao / youku / hangzhou等国际通用的名称，可视同英文。 -
变量命名：使用lowerCamelCase风格，遵从驼峰形式。
正例： localValue / getHttpMessage() / inputUserId -
类命名：类名使用UpperCamelCase风格，遵从驼峰形式，但以下情形例外：（领域模型的相关命名）DO / BO / DTO / VO等。
正例：MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion 反例：macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion -
函数命名：使用lowerCamelCase风格，遵从驼峰形式。
正例： localValue / getHttpMessage() / inputUserId -
常量：常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚。
正例： MAX_STOCK_COUNT 反例： MAX_COUN
-
-
项目结构规约：
- 项目包含：
- controller 请求转发。
- service 定义请求处理逻辑
- mapper 持久层
- utils 工具类包
- config 配置类包
- 配置文件路径：src/main/resources
- *.yml spring 配置文件
- mybatis/mapper 存放mybatis mapper文件和相关配置文件
- 项目包含：
-
各层命名规约：
- Service/mapper 层方法命名规约
- 获取对象的方法用 select 做前缀。
- 插入的方法用 save/insert 做前缀。
- 删除的方法用 remove/delete 做前缀。
- 修改的方法用 update 做前缀。
- Service/mapper 层方法命名规约
-
安全规约：
-
对除登录，登出等请求，进行权限判断。
-
用户敏感数据进行隔离
-
-
其他规约：
-
日期格式：yy-MM-dd HH:mm:ss
-
获取当前毫秒数System.currentTimeMillis();而不是new Date().getTime();
说明：如果想获取更加精确的纳秒级时间值，用System.nanoTime()。在JDK8中，针对统计时间等场景，推荐使用Instant类。
-
前端规范编程规范
JavaScript代码规范
- 缩进
每一层级由4个空格组成，避免使用制表符（Tab）进行缩进。- 行的长度
每行长度不应该超过80个字符，多于80个字符，应该在运算符后换行，下一行增加两级缩进（8个字符）
doSomething(argument1,argument2,argument3,argument4,
atgument5);
-
运算符间距
-
二元运算符前后必须使用一个空格保持表达式整洁，操作符包括运算符和逻辑运算符。
-
//好的写法 var found = (value[i] === item); if(found && (count > 10)){ doSomething(); } -
括号间距
-
使用括号时，紧接左括号之后和紧接右括号之前不应该有空格。
-
对象直接量
-
起始左花括号应当同表达式保持一行
-
每个属性的名值对应当保持一个缩进，第一个属性应当在左花括号后另起一行
-
每个属性的名值对使用不含引号的属性名，其后紧跟冒号（之前不含空格）
-
若属性值是函数类型，函数体在属性名之下另起一行，而且其前后均应保留一个空行
-
一组相关属性前后可插入空行提升代码的可读性
-
结束的右花括号独占一行
var object = { key1:value1, key2:value2, func:function() { //doSomething }, key3 = value3 };
-
-
当对象字面量作为函数参数时，若值是变量，起始花括号应当同函数名在同一行。
-
doSomething({ key1:value1, key2:value2 }); -
注释
-
1.单行注释
- 独占一行的注释，用来解释下一行代码
- 在代码行的尾部的注释，用来解释它之前的代码
- 多行，用来注释掉一个代码块
-
代码行尾单行注释的情况，应该确保代码结尾同注释之间至少一个缩进
单行注释之前要空格 -
if (condition) { //如果代码执行到这里，表明通过了安全检查 allowed(); } -
行内注释
var result = something + somethingElse; // 行内注释 -
变量声明
- 变量定义放在函数开头，使用var表达式每行一个变量
- 除首行，所有行都应该多一层缩进使变量名能够垂直方向对齐
- 初始化的变量应当在未初始化变量之前
-
var count = 10, name = "Nicoho", found = false, empty; -
函数声明
-
- 函数名和开始圆括号之间不应该有空格
- 结束圆括号和右边起始花括号应该有空格，右侧花括号和函数关键字保持一行
- 参数名之间应当有在逗号之后保留一个空格
- 立即被调用的函数应当在调用的外层用圆括号包裹
-
function outer(arg1, arg2){ var count = arg1, name = arg2, found = false, empty; function inner(){ //代码 } //调用inner()的代码 } -
命名
- 变量命名应当采用驼峰命名格式，首字母小写，每个单词首字母大写，第一个单词应当是一个名词，不要在变量命名中使用下划线
- 函数命名也采用驼峰命名格式，首字母小写，第一个单词应当是动词，和变量名进行区分
- 构造函数命名采用驼峰命名格式，首字母大写，以非动词开头
- 常量的命名应当是所有字母大写，不同字母之间用单个下划线隔开
- 对象的属性和方法命名同变量和函数，私有属性或者方法，在前面加一个下划线
-
赋值
-
给变量赋值时，如果右侧是含有比较语句的表达式，需要用圆括号包裹
-
三元操作符
-
三元操作符应当仅仅用在条件赋值语句中，而不要作为if语句的替代品
-
var value = condition ？ value1 ： value2; -
语句
-
1、简单语句
每行最多只包含一条语句，所有简单的语句以分号（；）结束。
2、复合语句- 括起来的语句应当比较复合语句多缩进一个层级
- 开始的大括号应当在复合语句所在行的末尾；结束的大括号独占一行，且与符合语句开始保持同样的缩进
- 若是if语句开始的关键字，其后紧跟一个空格，起始大括号在空格之后
HTML代码编写规范
-
HTML头部文档类型
-
建议使用 text/html 格式的 HTML。
避免使用XHTML，因为XHTML以及它的属性，比如application/xhtml+xml在浏览器中的应用支持与优化空间都十分有限。
<!DOCTYPE html> -
HTML标签的闭合
-
1、自闭合的标签可以无需闭合
推荐的方式：<input type="text" name="antzone"/>
2、可选闭合标签建议闭合
3、闭合标签必须闭合 -
HTML页面使用双引号，标签和标签属性统一使用小写形式
-
缩进
-
缩进使用soft tab（4个空格），嵌套的节点应该缩进；
-
HTML标签嵌套规则
-
1、HTML4/XHTML的嵌套规则
（1）内联元素不能嵌套块元素
（2）p元素和h1~h6元素不能嵌套块元素
（3）ul,li/ol,li/dl,dt,dd拥有父子级关系的标签；ul、ol下都只能跟li，dl下只能跟dt.dd
（4）a标签不能嵌套a；
2、HTML5元素嵌套规则
元素的分类不再是块元素或内联元素这样来分类（其实从来就没有这样分），而是按照如下分类来分：Flow（流式元素）、Heading（标题元素）、Sectioning（章节元素）、Phrasing（段落元素）、Embedded（嵌入元素）、Interactive（交互元素）、Metadata（元数据元素）
使用语义化标签，尽量少的使用毫无意义的标签，仅仅用于设置样式，语义化的HTML结构，有助于搜索引擎理解，另一方面多人协作时，能迅速了解开发者意图 -
HTML多媒体回溯
-
页面中的图片、视频和canvas 动画等都要确保有替代的显示内容。
图片文件我们可采用有意义的备选文本（alt属性规定），视频和音频文件我们可以为其加上说明文字或字幕。
例如：<img src="antozen.jpg" alt="网络图谱"> -
代码格式规则
-
- 每一个块状元素，列表元素和表格元素后，加上一新空白行。
- 内联元素写在一行内，块状元素还有列表和表格要另起一行。
-
内容、表现和行为分离
-
尽量在文档和模板中只包含结构性的HTML；而将所有表现代码，移入样式表中；将所有动作行为，移入脚本之中。
-
此外，为使得它们之间的联系尽可能的小，在文档和模板中也尽量少地引入样式和脚本文件。
-
主要规则如下:
-
（1）.页面中尽量不要引入超过两个样式表，例如main.css和vendor.css。
-
（2）.页面中保证只引入一个js文件（如果有多个文件，将它们合并压缩后引入）。
-
（3）.不要使用内联样式和内部样式。
-
（4）.不使用元素中表象的属性，例如align="center"。
结构的搭建 -
-
采用HTML5标准时开头应该加上
-
应在head标签中引入CSS文件，这样浏览器就可以在输出HTML之前获取CSS信息
-
在标签的末尾引入JavaScript文件，这样可以在页面显示之后再编译JavaScript文件，以加快页面读取速度，同时有助于JavaScript对页面中的元素进行操作
-
-
对元素的操作应添加在JavaScript代码中，而不要在HTML中添加，下面这个例子就是错误的，这样后期难以维护
-
HTML布尔属性值
-
HTML5规范中 disabled、checked、selected 等属性不用设置值。
-
HTML代码注释
-
如果可能尽量不写注释，尽可能减少文档的体积；如果必须要添加注释，那么就要遵循如下规则:
-
（1）.详尽注释，解释代码解决问题、解决思路、是否为新鲜方案等。
（2）.模块注释，github建议不使用模块结束注释。
（3）.待办注释
如：<!-- TODO:待办事项 --> -
网页标签语义化
-
- 尽可能少的使用无语义标签div和span
- 语义不明显时，可用p也可用div的地方，尽量使用p，因为p默认有上下边距，去除样式后的可读性更好，对兼容特殊终端有利
- 不要使用纯样式标签，例如bfontu,改用CSS设置语义上强调的文本可以包在strong和em标签里，strong的默认样式是加粗，而em的默认样式是斜体
-
属性
-
1.id 和 class
-
- class 用于标识高度可复用组件，因此应该排在首位。id 用于标识具体组件，应当谨慎使用（例如，页面内的书签），因此排在第二位。
- id一般用于网页大致布局，比如标志、导航、主体内容、版权，规范命名为#logo , #nav, #content ,#copyright。
-
一般项目中class用于css中，id被js用来操作dom且不添加样式，（jq操作class一般不加样式）。
