-
Notifications
You must be signed in to change notification settings - Fork 112
技术规范
这个页面主要介绍启动器开发中需要遵循的诸如命名规范、目录规范等。
尚未完工,欢迎各位开发者来共同维护这个页面。
Note
此处内容大多数来自官方文档所提及的或是一些成熟的开源项目所遵循的规范,但并不完全一致。
使用命名规范的好处是让代码更加 "一目了然",而不是靠 IDE 的上下文提示来判断一个元素的作用域或是类型,以尽可能避免一些因混淆作用域或类型而导致的失误。
至于为什么很多地方与上游的代码风格不一致,问就是 PCL 本体的大多数设计都不是很规范的,包括命名格式很多都是瞎几把写.... CE 已经尽可能规范化了,但目前也有很多很多地方并没有遵循规范,如果你有空闲时间和精力,欢迎提交 PR 帮助修复它们,同时如果不是 CE 特有的更改,请尽可能向上游而不是 CE 提交。
包括局部/全局变量、参数、属性、事件等原生支持赋值类符号的元素,若未说明静态则为非静态。
| 类别 | 命名规范 | 示例 |
|---|---|---|
| 局部变量, 方法参数, 构造器参数 | camelCase |
name runningThread resourceMap
|
| 私有属性, 私有只读全局变量 | _PascalCase |
_Items _PageMap
|
| 私有全局变量, 静态私有全局变量 | _camelCase |
_parameters _runningThreads _hasDisposed
|
| 主构造器属性 (record), 其它 | PascalCase |
Name CurrentThread ActivePageCollection
|
面向对象中对函数类型成员的称呼,由于托管式面向对象语言通常都没有真正的 "顶层" 概念,也就几乎不存在不是方法的函数,所以习惯统一称为 "方法"。
| 类别 | 命名规范 | 示例 |
|---|---|---|
| 非私有方法, 静态非私有方法, 局部方法 | PascalCase |
Start() ComposeMessage() WriteLogItem()
|
| 私有方法 | _PascalCase |
_StartInternal() _RaiseChanged()
|
包含但不限于类、接口、枚举、记录、委托等各种可以作为类型的元素。
| 类别 | 命名规范 | 示例 |
|---|---|---|
| 接口 | IPascalCase |
ICollection ILifecycleService IConfig
|
| 其它 | PascalCase | 略 |
| 类别 | 规范 |
|---|---|
| 事件 | 不应以 On 开头 |
AutoResetEvent ManualResetEvent ManualResetEventSlim 等 |
应以 Event 结尾 |
Important
此处部分内容来自仓库原 CONTRIBUTING.md 文件,感谢原作者 @WorldHim @wyc-26 @3gf8jv4dv 的贡献。
此处格式适用于 单行提交信息 和 PR 标题。
type(scope?): digest
type 应使用英文小写,具体分类见下方,提倡使用缩写,但你也可以选择使用完整单词。
scope 应使用英文,说明这个提交影响的模块或子系统,无需严格使用名词结尾,若无特殊需求应全部小写且每个单词中间使用短横线连接。如 profile lifecycle java-manage rpc 等。
digest 应尽量使用中文,阐述这个提交具体做了什么事,并在必要的专业名词处使用英文。注意需以动词原型开头,必要时可添加修饰成分,如 支持可选的高级材质 默认启用 RPC 服务 修复 Java 8 及以前的版本无法被正确识别。
type 包含以下种类:
-
featfeature- 引入新特性,通常是用户可感知的更改,如深色模式、Java 管理;但也有时是只有开发人员可以感知的,如引入生命周期管理。 -
fix- 修复线上或开发中发现的 bug,使程序行为恢复预期。 -
impimprove- 对现有功能进行交互体验、可读性等方面的优化,通常是用户可感知的更改。 -
refrefactor- 重构现有代码结构或实现方式,不大幅改变外部功能,只是改善可维护性。 -
docs- 仅修改文档内容,如 README、注释、API 文档等,不涉及程序逻辑。 -
style- 与功能无关的代码格式调整,包括但不限于空格、缩进、分号、命名风格等。 -
perfperformance- 专门针对性能的优化,如算法改进、缓存方案、渲染优化等。 -
test- 添加或修改单元测试、集成测试、测试脚本等。 -
chore- 构建流程维护、依赖升级、项目配置调整等与业务逻辑无关的杂项。 -
bump- 版本相关更改,如发布新 release 版本。 -
ci- 修改 CI/CD 配置文件、自动化脚本、构建管道等。
Note
scope 后面的冒号与 digest 中间应留有一个空格。
有些 type 比较泛用,但在有更接近的分类时,请勿将其归类到泛用分类中。例如,一些常常被归类为 fix 的提交中,修复 CI 构建失败应属于 ci,修复一些在无限提升设备性能的情况下可以缓解甚至自动修复的问题应属于 perf 等;一些常常被归类为 feat 的提交中,更改项目构建配置、添加依赖项应属于 chore 等。
digest 应避免使用过去时、将来时、名词短语以及含糊不清、无法看出具体相关性的描述。例如 深色模式 更正了 typo 一个高占用功能现在会默认关闭,正确的写法示例分别为 适配深色主题 更正某某位置的某某 typo 默认关闭高占用的某某功能。一个简洁清楚的 digest 通常不应超过 30 个汉字 或 50 个英文字母。
digest 末尾不应有句号。
此处格式适用于多行提交信息。
type(scope?): subject
body
footer
第一行的规则与上述简单格式基本一致,但此处 subject 无需呈现 digest 的完整内容。
body 详细描述提交的内容,应包含修改的动机以及与之前行为的对比 (如有)。
footer 包含 Breaking changes 和 Co-authored 部分,若有破坏性改动或合作内容应在此处写明,若没有则可不包含 footer 部分。
也可在 footer 中包含相关联的 issue 编号,如 Close #234,若有多个则用英文半角逗号分开,如 Close #234, #114, #514。
适用于撤消某个提交或 PR 的修改,提交信息以 revert: 开头。
revert: hash
message
hash 为原提交节点的 hash 内容或原 PR 的 id (以 # 开始),message 为完整的原提交信息,包括首行。
提交内容的换行符与文件编码差异可能会产生大量奇奇怪怪的无用更改,不方便 review 和后期溯源,因此统一要求提交 LF 换行符与标准 UTF-8 编码 (不附带 BOM)。
因换行符或编码造成大量无用更改的 PR 可能会被要求重新提交或直接关闭,因此请务必注意。
Tip
Git 可以自动处理提交内容的换行符,因此不需要手动管理本地文件的换行符,详情参考 GitHub 文档页面。
Tip
Rider 应当默认使用标准 UTF-8 编码,但微软的东西比如 Visual Studio 可能会时不时偷偷加个 BOM。因此提交时请务必注意文件首行是否存在更改,若存在,大概率是多了个 BOM 符号。