📏 规 范
《阿里规约》
----现代软件架构的复杂性需要协同开发完成,如何高效地协同呢?无规矩不成方圆,无规范难以协同,比如,制订交通法规表面上是要限制行车权,实际上是保障公众的人身安全,试想如果没有限速,没有红绿灯,谁还敢上路行驶。对软件来说,适当的规范和标准绝不是消灭代码内容的创造性、优雅性,而是限制过度个性化,以一种普遍认可的统一方式一起做事,提升协作效率,降低沟通成本。代码的字里行间流淌的是软件系统的血液,质量的提升是尽可能少踩坑,杜绝踩重复的坑,切实提升系统稳定性,码出质量。
1. 工具
1.1 emoji 指南 git emoji
emoji | emoji 代码 | commit 说明 |
---|---|---|
🎨 | :art: |
改善代码的结构/格式 |
⚡️ | :zap: |
提高性能 |
🔥 | :fire: |
删除代码或文件 |
🐛 | :bug: |
修复bug |
🚑️ | :ambulance: |
关键修补程序 |
✨ | :sparkles: |
引入新功能 |
📝 | :memo: |
添加或更新文档 |
🚀 | :rocket: |
部署东西 |
💄 | :lipstick: |
添加或更新UI和样式文件 |
🎉 | :tada: |
开始一个项目 |
✅ | :white_check_mark: |
添加或更新测试 |
🔒️ | :lock: |
解决安全问题 |
🔖 | :bookmark: |
发布/版本标签 |
🚨 | :rotating_light: |
修复编译器/ linter警告 |
🚧 | :construction: |
工作正在进行中 |
💚 | :green_heart: |
修复CI构建 |
⬇️ | :arrow_down: |
降级依赖项 |
⬆️ | :arrow_up: |
升级依赖项 |
📌 | :pushpin: |
引脚依赖于特定版本 |
👷 | :construction_worker: |
添加或更新CI构建系统 |
📈 | :chart_with_upwards_trend: |
添加或更新分析或跟踪代码 |
♻️ | :recycle: |
重构代码 |
➕ | :heavy_plus_sign: |
添加依赖项 |
➖ | :heavy_minus_sign: |
删除依赖项 |
🔧 | :wrench: |
添加或更新配置文件 |
🔨 | :hammer: |
添加或更新开发脚本 |
🌐 | :globe_with_meridians: |
国际化和本地化 |
✏️ | :pencil2: |
修正错别字 |
💩 | :poop: |
编写需要改进的错误代码 |
📦️ | :package: |
添加或更新编译的文件或包 |
1.2 git commit 规范
格 式
<!-- header -->
<type>(<scope>): <subject>
<!-- 空一行 -->
<body>
<!-- 空一行 -->
<footer>
其中 Header
必填,Body
Footer
选填。
不管是哪一个部分,任何一行都不得超过100个字符。
Header
Header
部分只有一行,包括三个字段:type
(必需)、scope
(可选)和 subject
(必需)
- type
type
用于说明 commit
的类别,只允许使用下面7个标识
feat
:新功能(feature)fix
:修补bugdocs
:文档(documentation)style
: 格式(不影响代码运行的变动)refactor
:重构(即不是新增功能,也不是修改bug的代码变动)perf
:性能、体验优化test
:增加、更新测试chore
:构建过程或辅助工具的变动build
:构建变动ci
:集成变动revert
: 回滚某个提交
如果 type
为 feat
和 fix
,则该 commit
将肯定出现在 Change log 之中。其他情况由你决定,要不要放入 Change log,建议是不要。
- scope
scope
用于说明 commit
影响的范围,比如数据层、控制层、视图层等等,视项目不同而不同。
- subject
subject
是 commit
目的的简短描述,不超过50个字符。
- 以动词开头,使用第一人称现在时,比如
change
,而不是changed
或changes
- 第一个字母小写
- 结尾不加句号
Body
Body
部分是对本次 commit
的详细描述,可以分成多行。
Footer
Footer
部分只用于两种情况。
- 不兼容变动
如果当前代码与上一个版本不兼容,则 Footer 部分以BREAKING CHANGE开头,后面是对变动的描述、以及变动理由和迁移方法。
- 关闭 Issue
如果当前 commit 针对某个issue,那么可以在 Footer 部分关闭这个 issue 。
1.3 GitHub 缩写
- PR: Pull Request. 拉取请求,给其他项目提交代码。
- LGTM: Looks Good To Me. 朕知道了 代码已经过 review,可以合并。
- SGTM: Sounds Good To Me. 和上面那句意思差不多,也是已经通过了 review 的意思。
- WIP: Work In Progress. 传说中提 PR 的最佳实践是,如果你有个改动很大的 PR,可以在写了一部分的情况下先提交,但是在标题里写上 WIP,以告诉项目维护者这个功能还未完成,方便维护者提前 review 部分提交的代码。
- PTAL: Please Take A Look. 你来瞅瞅?用来提示别人来看一下。
- TBR: To Be Reviewed. 提示维护者进行 review。
- TL;DR: Too Long; Didn't Read. 太长懒得看。也有很多文档在做简略描述之前会写这么一句。
- TBD: To Be Done(or Defined/Discussed/Decided/Determined). 根据语境不同意义有所区别,但一般都是还没搞定的意思。
2. 命 名
2.1 变 量
- 驼峰命名
- 代表含义优先显示:
loadingFormloadingList``refForm
2.2 方法
get
获取某值的方法query
查询的方法,get
调用query
或其他
2.3 CSS
- 使用中划线:
a-header-img
3. UI
3.1 按钮
- 默认增加
icon
- 交互时,面板操作按钮增加
loading
3.2 dialog
- 查看类,右上角有关闭按钮
- 操作类,右上角无按钮
- 默认新增修改类,不增加
top
- 列表、操作,增加
top(2vh 6vh 10vh)
3.3 表格
- 表格中操作栏
width
,根据按钮数量 *60
增加
4. 图片类
4.1 图片加载
- 若非必要,不要同时加载多张图片
- 图片加载需要时间