Kubernetes的代码规范 Kubernetes的代码规范

动机:
从换了工作以后开始做云方面的开发之后，一直思考如何再提高自己的代码质量。
发现了这篇文档，这是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
- 命名
  - 【Kubernetes的代码规范】在选择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
  - 包括修改过的第三方代码和摘录