Wow56 个人知识库

# Coding Style

# 空行

  • 空行不要太频繁，比如 20 行内不要使用换行。
  • 如果感觉必须要使用空行去区分逻辑的时候，首先看看是不是可以拆分方法，如果不至于进行拆分方法，可以使用换行。
  • 一般一次空一行。

# 引号

  • 优先级：无引号 > 单引号 > 双引号，比如在字符串声明值的时候，三种方式都可以用，这个时候就按照优先级的先后进行使用。

# 注释

# 什么时候要有注释

  • 描述性的，比如描述一个文件、类、方法、流程的时候，尤其是项目有特定规范时，一定要写以便生成 API 文档。
  • 代码逻辑复杂导致的可读性低的地方。
  • 代码作用不直观时，添加注释解释这样用的原因。
  • 存在多个方案时，注释上这样做的原因。
  • 因为某些限制确实无法保持一致的，注明原因。
  • 参考了外部资料，注明链接，方便别人查看。
  • 临时标记：TODO、FIXME、HACK、OPTIMIZE、REVIEW 等。

被注释掉的代码，如果没有用就删除，临时注释的标明原因。

# 命名

首先去术语表中查找，表中有的使用表中的，表中没有的先查看上文中之前使用的。最后再使用

  • 计数用 count、times，总和用 sum。不要用 time，有歧义。
  • 时间使用 xxxAt 的格式，注意时态。比如：已经发布 publishedAt，将发布 publishAt。
  • 是否使用 isXXX、doesXXX、shouldXXX、canXXX 的格式。注意使用时要符合基本语法。

# 日志

  • 应为固定字符串，中间不要拼接任何变量，变量应该放到 context 里。
  • 正式的非口语化的陈述句，英文注意时态且首字母应大写（代码标识符例外，应保持原样），句号可加可不加，保持一致即可。

# 异常

  • 不要吞掉异常，除非是确切知道这个问题大概率会出现。还有，捕获以后一定要处理。
  • 保留原始错误信息。
  • 若要重试，必须要加次数限制，并做好封装。

# 错误反馈

  • 服务器端
    • 进行使用框架和协议的 code。
    • 避免使用数字 error code,可以使用 string code。
    • message 也要尽量复用，不要带字段名，比如使用“can not be blank”，而不是"xxx can not be blank"。对于代码，哪个字段的问题可从 errors 的 key 得出，对于用户，界面上要把该错误消息跟其 input 对应，也不存在歧义。
  • 前端
    • 比如，输入表单，只需把服务端返回的 errors 直接挂到整个表单上，即可自动根据 key（即字段名）关联对应的 input，并将错误显示到 input 下。
    • RESTful API 的结构，见知识库中图片（已存到本地）。

# HTML & CSS

  • HTML 格式
    • 外部链接必须具有 rel="noopener" 和 target="_blank" 属性。
    • a 标签必须有标题属性。
    • 标签的属性内容必须小写，属性值必须用引号括起来。
    • 所有代码使用小写。
    • 属性和属性值之间的等号前后没有空格。
    • 像 checked、disabled 和 required 这样的布尔属性值是多余的，必须省略。
    • 单行注释在注释标记前后必须有空格。比如 <!-- comment -->，comment 前后要有空格。
    • 单行注释必须放在标签之前。
    • 图片必须有 alt 属性。
  • CSS 格式
    • 必须避免内联样式，不要把样式内容放在一行，要使用换行。
    • style 样式中的 type="text/css" 属性必须省略。
    • 除非需要，否则不要在 0 后面使用单位。
    • 注意缩进。
    • 在每个声明后使用分号。
    • 在属性名称的冒号后使用空格。
    • 在最后一个选择器和声明块之间使用一个空格。
    • 始终为每个选择器和声明另起一行。
    • 两种规格之间加空行。
    • 对属性选择器和属性值使用单引号，而不是双引号。
    • 不要在 URI 值中使用引号。

# JavaScript

  • 类成员排序：静态属性、静态方法、实例属性、构造方法、实例方法，公开方法写在私有方法前面。
  • 类私有成员要加下划线前缀。
  • 避免使用内联样式，要使用换行。
  • 外部 JS 代码的加载必须在 body 标签内。
  • 必须省略 script 标签的 type="text/javascript" 属性。
  • 使用 var 声明变量，不指定 var 时，该变量将被放置在全局上下文中，可能会破坏现有值。此外，如果没有声明，则很难判断变量存在于哪个范围内。
  • 不使用 const 关键字，因为 Internet Explorer 不支持它。
  • 变量使用全部大写，单词之间使用 _ 进行分割。
  • 始终使用分号。

# Java

  • 抽象类命名使用 Abstract 或 Base 开头。
  • 异常类命名使用 Exception 结尾。
  • 测试类命名以它要测试的类的名称开始，以 Test 结尾。
  • 类型与中括号紧挨相连来表示数组，比如 int[]。
  • POJO 类中的任何布尔类型的变量，都不要加 is 前缀，否则部分框架解析会引起序列化错误。
  • 在 long 或者 Long 赋值时，数值后使用大写字母 L，不能是小写字母 l，小写容易跟数字混淆，造成误解。
  • 大括号
    • 大括号内为空，写成 {}，大括号中间无需换行和空格。
    • 如果是非空代码块则：
      • 左大括号前不换行。
      • 左大括号后换行。
      • 右大括号前换行。
      • 右大括号后还有 else 等代码则不换行。
      • 表示终止的右大括号后必须换行。
  • if/for/while/switch/do 等保留字与括号之间都必须加空格。
  • 类型强制转换时，右括号与强制转换值之间不需要任何空格隔开。
  • 单行字符数限制不超过 120 个，超出需要换行，换行时遵循如下原则：
    • 第二行相对第一行缩进 4 个空格，从第三行开始，不再继续缩进。
    • 运算符与下文一起换行。
    • 方法调用的点符号与下文一起换行。
    • 方法调用中的多个参数需要换行时，在逗号后进行。
  • 所有的覆写方法，必须加 @Override 注解。
  • 不能使用过时的类或方法。
  • BigDecimal 的等值比较应使用 compareTo() 方法，而不是 equals() 方法。

# 讨论区

由于评论过多会影响页面最下方的导航，故将评论区做默认折叠处理。

点击查看评论区内容，渴望您的宝贵建议~
Last Updated: 6/10/2022, 3:54:48 PM

←