go语言代码规范

指南篇

编码风格原则

• 清晰：代码的目的和原理对读者来说是清晰的
• 简单：代码以最简单的方式完成其目标
• 简明：代码具有较高的信噪比
• 可维护性：编写的代码可以很容易维护
• 一致：代码与广泛的谷歌代码库风格一致

清晰

清晰主要是通过有效的命名、有用的注释和有效的代码组织来实现的。

清晰与否要从代码的读者角度来看，而不是从代码的作者的角度来看。代码的易读性比易写性更重要。

代码的清晰性有两个不同的方面：

• 代码实际上在做什么？
• 为什么代码在做它所做的事？

代码实际上在做什么

• 使用更具描述性的变量名
• 添加额外的注释
• 用空白和注释来分隔代码
• 将代码重构为独立的函数/方法，使其更加模块化。

为什么代码在做它所做的事

代码的原理往往是通过变量、函数、方法或包的名称来充分传达的。如果这些元素名称无法做到这点，那么添加注释就会变得很重要。当代码包含读者可能不熟悉的细微差别时，解释“为什么”将变得尤其重要。

注释最好是解释为什么要做某事，而不是解释代码在做什么。

简单

• 从上到下都易于阅读
• 不假设你已经知道它的工作原理
• 不假设你能记住前面所有的代码
• 没有不必要的抽象层次
• 在平凡代码中没有引起人们注意的名字
• 让读者清楚地了解价值和决策的传播情况
• 有注释，解释为什么，而不是代码在做什么，以避免将来出现偏差
• 有独立的文档
• 拥有有用的错误和有用的失败测试用例
• 通常与“故作聪明的”代码相互排斥

要控制代码的复杂性

简明

简明的Go代码具有很高的信噪比。它很容易分辨出相关的细节，而命名和结构则可以引导读者了解这些细节。

理解和使用常见的代码结构和地道用法对于保持高信噪比也很重要。例如，下面这个代码块在错误处理中非常常见，读者可以很快理解这个代码块的意图：

// Good:
if err := doSomething(); err != nil {
    // ...
}

如果代码看起来与此非常相似，但却有细微的不同，读者可能不会注意到这种变化。在这样的情况下，值得故意“提高”错误检查的信号，我们可以通过添加一个注释来引起注意。

// Good:
if err := doSomething(); err == nil { // if NO error
    // ...
}

可维护

• 易于被未来的程序员正确修改
• 具有结构化的API，使其能够优雅地扩展
• 清楚它所做的假设，并选择与问题结构相对应的抽象，而不是与代码的结构相对应。
• 避免不必要的耦合，不包含未用到的功能特性。
• 拥有一个全面的测试套件，以确保承诺的行为得到维护以及重要的逻辑是正确的，并且在测试失败的情况下为开发人员提供清晰、可操作的诊断

可维护的代码还可以避免将重要的细节隐藏在容易被忽视的地方。

一致

一致性的代码是指在更广泛的代码库中，在一个团队的代码中或一个包的范围内，甚至在一个文件中，看起来、感觉和行为都类似的代码。