-
Notifications
You must be signed in to change notification settings - Fork 111
技术规范
Warning
PCL-CE 仓库内 Wiki 已被迁移至 docs.pclc.cc,此处所记载的内容可能过时。也请不要再对此 Wiki 进行维护。
这个页面主要介绍启动器开发中需要遵循的诸如命名规范、目录规范等。
尚未完工,欢迎各位开发者来共同维护这个页面。
此处内容大多数来自官方文档所提及的或是一些成熟的开源项目所遵循的规范,但并不完全一致。
使用命名规范的好处是让代码更加 "一目了然",而非需要靠 IDE 的上下文提示来判断一个元素的作用域或是类型,以尽可能避免一些因混淆作用域或类型而导致的失误。
至于为什么很多地方与上游的代码风格不一致,问就是 PCL 本体的大多数设计都不是很规范的,包括命名格式很多都是瞎几把写.... CE 已经尽可能规范化了,但目前也有很多很多地方并没有遵循规范,如果你有空闲时间和精力,欢迎提交 PR 帮助修复它们。
包括局部/全局变量、参数、属性、事件等原生支持赋值类符号的元素,若未说明静态则为非静态。
| 类别 | 命名规范 | 示例 |
|---|---|---|
| 局部变量, 方法参数, 构造器参数 | 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 结尾 |
此处介绍项目开发中各类标准用法和注意事项。
参考 生命周期简介 页面。
任何对服务相关内容的调用,对于同步服务,均应确保在更晚的生命周期状态中调用,或在同状态的异步服务初始化或优先级更低的同步服务初始化中调用;对于异步服务,则只能在更晚的生命周期状态中调用。
若未确保上述调用顺序,则可能会引发各类由于服务尚未初始化而导致的异常,例如经典的 NullReferenceException InvalidOperationException 等。
参考 应用配置系统简介 页面。
为方便维护,请尽可能在核心库的 Config.cs 文件中添加配置项,并确保添加注释。若十分确保一个配置项仅在某一体系内部使用,则可在该体系内部声明。
注册任意配置项事件前请确保你的代码具有足够的性能,否则不要注册任何配置项事件。为保证配置值的全局一致性,配置系统的所有事件均同步执行,因此很容易暴露代码的潜在性能问题。
.NET 7 引入了 GeneratedRegexAttribute 特性在编译期预生成正则表达式匹配逻辑,可以极大提升正则表达式的运行时性能。因此要求代码新增的任何非已有体系的正则匹配均使用 GeneratedRegex,而不是动态初始化正则表达式;任何新增的传入正则参数的方法,除非有特殊需求,均应直接接受正则表达式实例而不是字符串实例。
GeneratedRegex 注解的规范用法请参考核心库 Utils/RegexPatterns.cs,推荐的做法是直接在这个文件中添加新的正则表达式声明。
.NET 7 引入了 LibraryImportAttribute 特性简化并在编译期预生成静态的封送代码,同时使得 P/Invoke 可以被 inline 优化。这在一定程度上提升了 P/Invoke 声明的性能,因此要求代码中 P/Invoke 调用统一使用 LibraryImport 取代 DllImport 用法,并注意利用静态封送特性(如本应传入指针导出数据时可以直接使用 Span 来安全处理类型并极大提升性能,更多特性请参考官方文档)。
Note
LibraryImport 要求使用 partial 关键字换掉 DllImport 要求的 extern 关键字。
Important
官方规范的可见性修饰由 private 放宽到了 internal,但为了提升可维护性,仍不建议将 P/Invoke 声明暴露到本类范围之外,因此使用 LibraryImport 声明的方法仍然推荐使用 private 修饰。
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: digest (hash)
hash 为原提交节点的 hash 内容或原 PR 的 id (以 # 开始),digest 为原提交信息首行。
提交内容的换行符与文件编码差异可能会产生大量奇奇怪怪的无用更改,不方便 review 和后期溯源,因此统一要求新文件使用 LF 换行符与标准 UTF-8 编码 (不附带 BOM)。
若修改已存在的文件,请注意遵循原有格式,不需优先考虑上述规则,以尽可能避免与其他分支中正在进行的更改产生冲突。
因换行符或编码造成大量无用更改的 PR 可能会被要求重新提交或直接关闭,因此请务必注意。
Tip
Git 可以自动处理提交内容的换行符,因此不需要手动管理本地文件的换行符,详情参考 GitHub 文档页面。
Tip
Rider 可在设置中指定默认使用标准 UTF-8 编码,但微软的东西比如 Visual Studio 可能会时不时偷偷加个 BOM。因此提交时请务必注意文件首行是否存在更改,若存在,大概率是多了个 BOM 符号。