• 微信公众号:美女很有趣。 工作之余,放松一下,关注即送10G+美女照片!

字节乱动–团队作业六:代码规范

开发技术 开发技术 1天前 4次浏览

字节乱动–团队作业六:代码规范

这个作业属于哪个课程 2021春软件工程实践|S班
这个作业要求在哪里 团队作业六——beta冲刺+事后诸葛亮
团队名称 字节乱动
这个作业的目标 记录代码规范
其他参考文献
汇总博客 beta冲刺+事后诸葛亮博客汇总
目录
  • 字节乱动–团队作业六:代码规范
    • 后端规范编程规范
    • 前端规范编程规范
      • JavaScript代码规范
      • HTML代码编写规范

后端规范编程规范

参考阿里巴巴Java开发手册终极版v1.3.0

  • 格式规约:

    • 缩进:采用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 做前缀。
  • 安全规约:

    • 对除登录,登出等请求,进行权限判断。

    • 用户敏感数据进行隔离

  • 其他规约:

    • 日期格式: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一般不加样式)。


程序员灯塔
转载请注明原文链接:字节乱动–团队作业六:代码规范
喜欢 (0)