关于kubernetes:Kubernetes的代码规范

41次阅读

共计 1932 个字符，预计需要花费 5 分钟才能阅读完成。

动机:
从换了工作当前开始做云方面的开发之后，始终思考如何再进步本人的代码品质。
发现了这篇文档，这是 kubernetes 倡议 contributor 恪守的代码规约，我感觉对于云开发其实都很具备参考价值。文章不多，简略翻译整顿一下，心愿对其余和我一样入门云的同学有所帮忙。

这是一个汇合，蕴含了我的项目中波及的，指导方针，格调倡议以及用不同语言写代码的提醒。

Bash
- https://google.github.io/styl…
- 确保编译，公布，测试和集群治理的脚本，在 macOS 上能够容许
Go
- Go Code Review Comments Go 代码审查评论（能够了解为一些常见的谬误汇合）
- Effective Go（go 语言的文档，入门 go 必看）
- 晓得并防止 go 语言的地雷
- 正文你的代码：
  - Go’s commenting coventions（go 的代码正文标准）
  - 如果代码的审查者问起某一处代码为什么那么写，那其实是一个那里须要增加正文的信号。
- 命令行的 flag，应该应用破折号，而不是下划线
  破折号:
```
./fakestuff --hello-world xxx
```
  下滑线：
```
./fakestuff --hello_world xxx
```
- 命名
  - 在抉择 interface 名字的时候，请思考到包名，以防止反复。
    - 举例：storage.Interface 就比 storage.StorageInterface 更好。
  - 不要在包名中应用大写，下划线和破折号
  - 在抉择包名的时候，请思考到包的父目录名字。
    - 所以文件 pkg/controllers/autoscaler/foo.go 的包名应该是package autoscaler, 而非package autoscalercontroller。
    - 除非有非凡起因，否则 package foo 应该和 go 文件所在目录名匹配。（即 go 文件应该在 /foo 下）。
    - 援用包的中央能够进行重命名以防止歧意。
    - 锁应该命名为lock，并且永远不应该被内嵌（永远放弃 lock sync.Mutex）。当以后有多个锁的时候，给每一个锁一个合乎 go 标准的不同名字 – statelock, maplock 等。
      此处增加一个内嵌构造的谬误应用案例：
```
type A struct {lock sync.Mutex}
type B struct {A // 此时 B 能够应用锁，然而其实应该给 B 也增加一个 lock}
```
- API 变更
- API 标准
- kubectl 标准
- 日志标准

所有的新包和新的重要性能，都必须有单元测试
表驱动测试是测试多个场景 / 输出的首选，参考: TestNamespaceAuthorization
重要的性能应该带有集成测试或者 e2e 测试
- 也蕴含新的 kubectl 和现有的次要性能，都须要集成测试或 e2e 测试
单元测试能够在 macOS 和 Windows 平台通过 – 如果你在应用 Linux 平台的特定性能，你的测试用例必须要么能够跳过其余平台，要么能够编译进去（当你的代码无奈在 windows 上编译的时候，在编译的时候跳过这些 linux 平台的特定指令）。
防止依赖 Docker hub（比方从 docker hub 上拉取镜像）。应用 gcr.io 作为代替。
防止期待一小段时间（或不期待）然乎期待一个异步执行的事件产生（比方：期待 1s，并预期某个 pod 开始运行）。应该应用“期待减轻试”作为代替。
能够参考测试标准以获取更多的倡议。

防止包蔓延。为新包找到一个适合的子目录。（详情能够参见 #4851 的探讨）
- 没什么好地位放的库，应该归属到 pkg/util 下。
防止通用的性能包。名字为“uitl”的包就很可疑。想法，想一个形容你须要的办法的包名。比方，一个解决期待操作的工具办法 Poll，应该放在一个名为wait 的包中，全称为wait.Poll。
文件名全副小些。
Go 源文件和目录应该应用下划线，而非破折号
- 包目录应该尽量避免应用多个单词，如果呈现“a_b”的包名，那么意味着为好拆分一个子目录:a/b
文档目录和文件名应该应用破折号而非下划线
形容零碎性能的人为示例，应该归属 /docks/user-guide 或者 /docs/admin, 具体取决于这是一个面向部署利用的用户还是集群管理员。理论利用例子属于/examples。
- 例子应该形容配置和应用这个零碎的最佳实际。
第三方代码
- 对于一般第三方代码的依赖，应该应用 go modules 进行治理，在 kubernetes 的 vendor 指南中中有形容。
- 其余的第三方代码，放在 /third_party 目录下
  - forked 的第三方 go 代码，放在/third_party/forked
  - forked 的 golang 规范库代码，放在 /third_party/forked/golang
- 第三方代码必须带有 licenses
  - 包含批改过的第三方代码和摘录