Skip to content

开发规约与建议

Jump to bottom
CLDXiang edited this page Apr 12, 2021 · 16 revisions

本页面中，

  • 【约定】是必须遵守的事项，如果无法满足【约定】中的要求，PR 将被要求修改
  • 【建议】是强烈推荐遵守的事项，如果没有满足【建议】中的要求，Reviewer 可以合理对 PR 提出改进要求

该页面是 Slack 中 pinned 消息的沉淀，有任何更新和新事项都会先在 Slack 中发布和讨论，并定期同步到这个页面。

开发环境

  • 操作系统任选，当前项目配置应该支持在所有主流操作系统上进行开发
  • 统一使用 VSCode 编辑器，安装并启用项目中推荐的所有插件（在 VSCode 插件页面搜索框输入 @recommended 查询）
    • 如果强烈坚持使用其他编辑器，请确保将其配置至可包含 VSCode 及所有推荐插件主要功能的程度，并且依照 .vscode/settings.json 中对各插件的配置进行相应调整。否则你的 PR 可能会因为代码风格与团队标准不符等原因被驳回

工作流程

每位开发同学的工作优先级

Review 他人 PR > 修改自己被 Request change 的 PR > 提新的 PR

这样可以尽量加快 PR 流动速度，防止 PR 积压造成工作阻塞或分支冲突。尽量保证每位同学在线上没有多于 1 个 WIP 的 PR。

事项从被提出到上线的流程

  1. 在 Issues 中点击 “New Issue” 来提出 Issue（如果你不太确定是否要提出 Issue，可以在 Slack 先讨论），选择合适的 Issue 模板并详细填写 Issue 说明，指定合适的 Label，如果该事项属于某个迭代期，可将其指定到对应 Project 中以将其放入看板
  2. 任何同学都可以接手未被指定 Assignee 的事项，将其指派给自己即可，如果有预期完成时间，可在对应 Issue 中留下一个 comment
  3. 在准备开始工作时，从仓库同步最新 master 分支（或其他分支，在有特殊需要时），新建一个分支来编写代码
  4. 工作进行过程中，可以将对应分支提前提 Pull Request，将 PR 打上 WIP Label 即可，在工作完成前不要指定 Reviewer
  5. 完成工作后，正式提 PR，并且 link 上对应 Issue（可在右侧配置，或者使用 closing keywords，如 resolve #233），按照 PR 模板要求详细写明 PR 中涉及的工作，设置合适的 Labels，并且指定 Reviewer。PR 提出后在 Slack 中对应的 GitHub App 发送的 PR 消息下 @ Reviewer
  6. 被指定的 Reviewer 尽快回应（可以 / 没空 review），在可以的情况下尽快进行 review，review 完后再 Slack 对应消息处 @ 一下 Assignee
  7. 此后 Reviewer 和 Assignee 间如果需要互相通知该 PR 的工作进程，尽可能在 Slack 同步通知一下对方
  8. PR 被 Approve 并且通过 CI 后，由 Owner / Assignee / Reviewer 中任一人合入 master 上线
  • 部分特殊的不便或者不必 Review 的事项可以跳过 Review，如更新二维码、JSON 等静态文件
  • 【约定】每个 PR，如果内容有需要放入更新日志告知用户的改动，需要在 PR 内顺便更新日志文件 public/changeLog.json ，如果是非常小的改动，可以就近在上一条日志中增加一个事项。如果是较大改动或者上一条日志时间比较远，需要新增一条日志
  • 【建议】如果要添加任何静态图像文件，请先在 tinyjpg.com 进行压缩后再提交，以减小图片文件体积对项目体积和网络性能的影响
  • 【约定】所有项目相关文档的排版请遵循中文文案排版指北中非“争议”部分的要求，同时【建议】在诸如 PR、Issues 等处也遵循其中的要求

Vue

  • 【约定】组件重构及新增组件的过程中，请使用 Vue 3 Composition API 的写法，一方面这是 Vue 官方建议的做法，在代码提示、TS 支持方面比 Vue 2 做得更完善；另一方面，使用 Composition API 可以很方便地抽离和复用组件逻辑，在同一组件内也可以更方便地组织代码，从而提高可读性和可维护性
  • 【约定】不要在 <template> 中用 ?? 运算符，会使编辑器中 Vetur 的代码高亮出错（或许会在此后的 Vetur 版本修复）

JavaScript

  • 【约定】变量命名尽量不要使用缩写/简写，以下情况除外：

    • 非常常见的缩写。见下方附例
    • 【仍不建议使用】上下文非常明显，为了方便书写代码进行的简写。如上文有 timeSlots，可以令 ts = timeSlots 以方便书写
      • 在循环上下文中，如 for ts of timeSlots、timeSlots.forEach((ts) => {}) 时，变量指代非常明确，可以使用缩写以方便内部使用
    • 有详细注释。变量名语义非常明确的情况下可以避免过于冗杂的注释，如果变量名无法准确表达其意义，请配合详细的注释

    附目前约定可用的缩写集合（如果需要添加可在 Slack 中对应的 pinned message thread 提议）：

    • result => res
    • error => err
    • request => req
    • response => resp

    注：以上缩写并不强制要求使用，仅是被允许使用的缩写集合

  • 【约定】对 JS 变量/函数定义/对象 key 等的注释请紧贴定义上方用 /** ... */ 格式书写，这样可以提供更好的代码提示，如对于

    /**
 * 计算悬浮元素相对视口的偏移量
 * @param current 悬浮元素
 * @param target 定位点元素
 * @param position 相对位置类型
 * @param offset 悬浮元素与定位点元素距离
 */
export function calculatePosition(
  current: HTMLElement | undefined,
  target: HTMLElement | undefined,
  placement: PlacementType,
  offset = 8,
): Position {
  ... // 函数体
}

    外部调用时会有如图的代码提示：

    合理使用注释带来的代码提示

    但也请勿滥用 /** */ 注释，在并不需要为下方变量定义增加代码提示的情况下仍用 /* */ 或 / / 注释

CSS

  • 【建议】不要在 Flexbox 容器内用 weight 和 height 控制子元素大小，在 safari 浏览器中会失效导致 overflow。参考因为这样做导致的 BUG
Clone this wiki locally