孤尽T31训练营06编码规约笔记

okokabcd
312 阅读4分钟

今天孤尽老师讲了Java开发手册的编程规约,了解到这个手册的起缘以及这里的每一条规约背后都是他们踩过的坑

image-20211107061530076.png

关于命名风格与代码格式的两个要求

1、命名体现代码元素特征

  1. 抽象类命名使用Abstract或Base开头
  2. 异常类命名使用Exception结尾
  3. 测试类命名以它要测试的类名开始,以Test结尾
  4. 枚举类名带上Enum后缀,枚举成员名称需要全大写,单词间用下画线隔开
  5. 类型与中括号紧挨相连来定义数组

2、命名最好望文知义

  1. 某些不规范的缩写会导致理解成本增加,比如condition缩写成condi
  2. 主流的编程语言基本上以英语为基础,此处望文知义的“文”指的是英文

关于常量定义的设计与规约

  1. [强制]不允许任何魔法值(即未经预先定义的常量)直接出现在代码中
  2. [强制]在long或者Long赋值时,数值后使用大写民字母L,不能是小写字母l,小写容易跟数字混淆,造成误解

关于注释

注释的误解

  1. 没啥用,反正不影响编译---一个月后自己都不理解自己写的代码了
  2. 为了怕老板说我没有注释
  3. 增加代码行数
  4. 对简单英文单词的傻瓜翻译

注释的作用

即便是离职或不在维护你写的代码了,你也在和后续的维护者在交流,别人通过你的注释、设计在与你进行另一种方式的交流---就像看书一样,也是同作者交流的一种方式

  1. 提高代码可读性
  2. 使程序条理清晰
  3. 方便后期代码维护
  4. 方便程序员间的交流沟通
  5. 生成帮助文档
  6. 警示作用,防止踩坑

注释的作用(通俗的说法)

  1. 附加说明
    1. 业务DETAIL规则,我轻轻地告诉你
    2. 这是一个架构上的决定
    3. 这是我在存储或中间件调用方式决定
  2. 部分与整体---盲人摸象
    1. 我告诉你大象的鼻子在哪里
    2. 我告诉你大象的整体样子是啥
    3. 我告诉你你摸到的是啥
  3. 风险提示---我是坑货
    1. 可以使用,请注意例外情况
    2. 临时写法,请饶行
    3. 魔法值,你不懂,我告诉你

关于前后端规约

  1. [强制]前后端交互的API,需要明确协议、域名、路径、请求内容、状态码、响应体
  2. [强制]前后端数据列表相关的接口返回,如果为空,则返回空数组[]或空集合{}
  3. [强制]服务端发生错误时,返回给前端的响应信息必须包含HTTP状态码,errorCode、errorMessage、用户提示信息四个部分
  4. [强制]在前后端交互的JSON格式数据中,所有的key必须为小写字母开始的lowerCamelCase风格,符合英文表达习惯,且表意完整
  5. [强制]errorMessage是前后端错误追踪机制的体现,可以在前端输出到type=“hidden”文字类控件中,或者用户端的日志中,帮助我们快速地定位出问题
  6. [强制]对于需要使用超大整数的场景,服务端一律使用String字符串类型返回,禁止使用Long类型
  7. [强制]HTTP请求通过URL传递参数时,不能超过2048字节
  8. [强制]HTTP请求通过body传递内容时,必须控制长度,走出最大长度后,后端解析会出错
  9. [强制]在翻页场景中,用户的输入参数小于1,则前端返回第一页参数给后端;后端发现用户的输入参数大于总页数,直接返回最后一页
  10. [强制]服务器内部重定向必须使用forward;外部重定向地址必须使用URL统一代理模块生成,否则会因线上采用HTTPS协议而导致浏览器提示“不安全”,并且还会带来URL维护不一致的问题
avatar
文章
阅读
粉丝