[业务产出] Review 规范（不断更新）

[PeterChen1997]

# 代码 review 规范

💡 更新与 2021.03.31

变量

• 命名是否符合规范
  • 函数：动词+名词
    • getUsers
  • 变量：
    • 尽量不要缩写
    • 命名扩展性
      • 如果在特定的业务组件中，则不需要将命名写的太过兼容，考虑可维护性比可扩展性更重要
      • 如果是通用组件，则相反，尽量避免吧命名写的太死，比如 uploadToAliyun 就没有 uploadToCDN 更好
      • 比如，使用 enableAnonymous 代替 enableAnonymousSwitch，也比较 ok
    • 命名规范
      • 尽量保证一个含义的变量，在整个代码中都叫同一个值
• 默认值
  • 组件中的变量默认值最好缺省值都为比较少使用的情况
    • 比如 showArrow 为 false
• 本地化 l10n
  • 不同于国际化【国际化也称为 i18n（因为“i”和“n”之间有 18 个字母）】
    • i18n 是内部机制，提供逻辑一致的机制来支持多语言多文化习惯的支持。
    • l10n 是体力活儿，按各个国家和地区的习惯制作界面文字图片排版等
  • 所有文本类型都需要通过 i18n 的包装
• immutable
  • 不手动修改入参或者 let 声明引用类型，都可以通过扩展运算符进行解决
• 注释
  • 正则表达式都要贴上注释
• 入参
  • 入参最好都使用对象来进行变量传递，这样内部的属性可以乱序传入，也可与缺省传入。如果按照顺序传入，则不行
  • 入参可以通过解构赋值的操作，压缩代码的空间
    • ({id}) ⇒ id
  • 对于同类型或者同功能的入参，可以考虑进行简化，边写边改
• 函数
  • 函数可以都是用 arrow function，这样的话可以节省一部分的代码空间

// ES5
var add = function(x, y) {
  return x + y;
};
// ES6
let add = (x, y) => { return x + y };

• 关联的同类变量
  • 维护 Single Source Of Truth 的原则，比如一个对象有四个 key，那么和这个四个 key 有关的地方就只有一个，其他都是用各种方法处理得出。后续更改就只用更改一个地方

逻辑 - JS

• 特殊情况判断
  • 数组：长度为 0 或为 undefined
• 依赖逻辑
  • 全局搜索上下文中，是否存在相应的关联逻辑
    • 搜索组件名
    • 搜索逻辑名
  • 修改了基础组件后，一定要确认相关功能是否有影响到其他地方，很容易出线上问题
• 表单逻辑
  • 表单的不同展示态下的数据是否都有效
    • 比如某些情况下不展示某 FormItem，则需要在数据发送时进行处理或不发送
  • input 的 type 不要用，内部有很多浏览器实现不同的特性
    • 比如 type=number, 有很多诡异的逻辑，最好还是使用默认 type，使用正则进行验证
  • 在基础组件上封装一层 FieldXXX，即可以比较好的使用基础组件
• 复用
  • 复用已有的业务组件可以大大提高开发效率，当然也要考虑可扩展性
  • 复用的逻辑要确认是否为特定场景下才能使用，避免使用场景错误
  • 合理使用工具库，如 conditional 来保证代码逻辑尽量简洁
• 三元运算
  • 活用 && 代替，可以不用返回额外的 null
    • 但是如果有 ?. 的场景能够满足，则使用 ?. 即可
  • 对于较长的三元运算可以
  • 避免嵌套三元表达式，尽量拆开
  • 对于一些简单的 if xx else xx 的逻辑，可以考虑直接用 a === b 能不能替代
• 常识
  • switch 一定要写 default
  • else if 要写 else
  • 方法用小写，组件用大写（比如 xxxRender
  • 不要写 magic number ！！！
• 重构
  • 重构时，可以把函数名直接重命名为 DeprecatedXXX，这样后面就不可能用错
    • 如果只是叫 XXXV2，下次可能不一定能能够 get 到
  • 如果没有用的逻辑，能删就删吧，或者注释后定期清理
  • 使用 inclueds 代替 indexOf ≠= -1
  • 删除代码的时候，先注释，并定期确认回顾问题
  • 数组有多个 api 链式调用的时候，可以尝试减少调用的次数，合并一些 map、find 的方法，减少时间复杂度
• 动画
  • 能够使用 CSS 则不要使用 JS，可能会涉及到重排和重绘，导致出现异常的渲染问题
    • 比如打断用户正在进行的输入

规范

• 函数注释可以从多个角度进行说明
  • 功能
  • 执行逻辑
• 避免使用 mutate api
  • 这里通过 eslint 禁止，再通过提供工具库进行避免

框架-React

• 编写规范
  • 视图和逻辑分开，使用专门的 store 或者 model 管理业务逻辑
  • 不要将非 boolean 值，作为渲染控制器
    • x - { status && (xxx)}
      • 如果 status 为 undefined 则会出现问题，把 undefined 渲染出来了
    • ✅ - {!!status && (xxx)}
  • 传入 hook 的参数需要 useMemo，避免 re-render 重复触发 hook
  • 条件渲染场景下，如果不满足不展示的话，可以直接使用变量 && 更简洁
• react-hook-form
  • 注册 control 需要传递默认值！
• props 设计
  • 复用性的思考
    • 比如对于 FormRow，传递 onRowClick 就比传递 setXXX 这种耦合性高的逻辑好
  • 粒度的思考
    • 如果一个组件传递的多个 props 都是相关的内容，可以考虑直接合并为一个参数，减少参数的数量
• 组件设计
  • 如果一个组件是通用组件，如评论组件，那么它的参数一定需要与业务解耦，避免耦合进业务的逻辑，一些业务影响功能的信息，可以在父组件调用的时候传递给组件
  • 善用 React 中的内置函数，可以用比如说 Children、cloneChildren 等管理和设计组件
  • 善用 children，把传入的内容交给外部控制

  • 组件管理需要拆分为 UI 组件+业务组件

• 性能优化
  • 使用 useMemo 和 useCallback 进行缓存，避免无效的变量创建
• hooks 设计
  • 如果考虑组件复用的话，可以尽量不要让 hooks 返回 JSX
  • 如果组件设计比较固定，可以直接封装进 hooks 内
  • useEffect 的入参必须要是 memo 的，否则会异常触发对应的执行逻辑
• state 设计
  • 避免使用一些无效的 state，比如不影响渲染的逻辑

样式-CSS

• 防御性 CSS 编程：[CSS] 防御型编程 in CSS #39
• 使用 sass 进行一些逻辑的复用
  • mixin —— 抽离常用的功能
    • 居中
    • font weight+size
  • var —— 对于特殊值以变量形式保存
    • 可以使用的范围 包括 colors、global、font...
• 确认特殊情况下的样式改动是否正常
  • 屏幕高矮
  • 屏幕宽窄
• 关于点击区域
  • 如 checkbox。此类较小的点击区域可以根据使用场景不同，对可响应的范围进行调整。比如 1414 的 icon，可以试用 2020 的点击响应区域
• 关于数值
  • 在单位内尽量不要出现小数
• 编写的 CSS 内容，尽量避免放大生效的范围，避免父子组件优先级不一致导致的样式冲突问题
  • 如果遇到冲突，可以考虑两种解决方案
    • 父组件优先级高：考虑将样式层级降低，拿出来
    • 子组件优先级低，尝试升高样式层级
• 关于嵌套
  • scss 中尽量不嵌套 css，避免导致样式层级过高，导致内容无法覆盖
• 命名
  • css 中的声明，尽量都使用类名，而不要使用标签选择器、或者自定义属性
    • 后续可能会存在冲突，而且不太好解决

类型-TS

• 写代码一定要用 TS
• 不要随意扩大类型（比如给类型的 type 加上 | null）
  • 可能会影响到在其他地方的使用逻辑
• 入参
  • 入参的默认值感觉可以尽量使用 optional，这样的话可以让使用方更加灵活，并且对于参数的处理都可以放在组件内
• 类型声明
  • 返回值如果可能为 Promise，则需要共同支持对应的type（如 Promise | boolean)

跨端

• 确认改动特性在其他前端业务端的表现一致

Review

• 代码 review 的 comments 一定要回复
• discussion 必须要提出者进行 resolve
  • 如果已经 approve 则可以自行 resolve
• 合并前
  • 最后确认一遍 rc 分支是否有最新代码，合入后确认一遍再 merge
  • 再次确认一遍 checklist，避免被前面的改动改出问题
• 考虑兼容性问题
  • 上线前的已有用户情形是否枚举
  • 上线后用户的行为反应是否符合预期

DOM

• 使用 indexedDB 的所有 API 都需要 try catch，保证兜底逻辑能够正常执行