Zen Of Go(译)

Ten engineering values for writing simple, readable, maintainable Go code. Presented at GopherCon Israel 2020.

• Each package fulfils a single purpose

  A well designed Go package provides a single idea, a set of related behaviours. A good Go package starts by choosing a good name. Think of your package’s name as an elevator pitch to describe what it provides, using just one word.

  译：

  每个 package 都要满足单一目的

  一个设计良好的 Go package 提供了一个单一的 idea，一组相关的行为。一个好的 Go package 首先要选一个好名字，把你的 包名 想成一次 电梯游说， 只用一个词去描述它提供的功能。

  注：

  elevator pitch：电梯游说。电梯游说这个名字本身传递着这样一个理念：你应该能在乘电梯的时间内，也就是大约30秒到两分钟之内完成介绍。

• Handle errors explicitly

  Robust programs are composed from pieces that handle the failure cases before they pat themselves on the back. The verbosity of if err != nil { return err } is outweighed by the value of deliberately handling each failure condition at the point at which they occur. Panic and recover are not exceptions, they aren’t intended to be used that way.

  译：

  显式处理错误

  健壮的程序是由 在表扬自己之前 处理失败情况的部分组成的。if err != nil { return err }，这条语句在每个故障发生时，有意识地即时处理故障，这种行为所带来的价值抵消了 语句表达上 的冗长。Panic 和 recover 不是异常，它们不应被显示处理。

  注：

  pat themselves on the back：直译为“拍拍背”，实际用来比喻鼓励、表扬、称赞一个人

• Return early rather than nesting deeply

  Every time you indent you add another precondition to the programmer’s stack consuming one of the 7 ±2 slots in their short term memory. Avoid control flow that requires deep indentation. Rather than nesting deeply, keep the success path to the left using guard clauses.

  译：

  [方法]尽早返回，而不是深度嵌套

  每次缩进，你都在 [阅读代码的] 程序员的头脑（stack:栈，存放方法运行时的数据，暗指人阅读代码时的大脑）中增加预设条件（precondition），这将消耗 “7±2短期记忆理论”中的一个信息块槽位。避免需要深度缩进的控制流（control flow）[代码]。 与其深度嵌套，不如使用卫语句（guard clauses）在左侧保持成功的路径。

  注：

  7 ±2 ：1956年，美国心理学家米勒（George A. Miller）教授发表了一篇重要的论文《神奇的数字7±2：我们加工信息能力的某些限制》，对人的短时记忆能力进行了定量研究。他发现，人类头脑最好的状态能记忆含有7±2项信息块，即一般为7并在5-9之间波动，在记忆了5-9项信息后人类的头脑就开始出错。

• Leave concurrency to the caller

  Let the caller choose if they want to run your library or function asynchronously, don’t force it on them. If your library uses concurrency it should do so transparently.

  译：

  把并发留给调用者

  让调用者自己选择是否要异步调用库或函数，不要强迫他们。如果你的库使用并发，// todo

• Before you launch a goroutine, know when it will stop

  Goroutines own resources; locks, variables, memory, etc. The sure fire way to free those resources is to stop the owning goroutine.

  译：

  在你启动一个 goroutine 之前，应该知道它何时停止

  goroutine 占有资源，锁，变量，内存，等等。释放这些资源的最可靠(fire way:消防车道)的方法是停止占用这些资源的 goroutine。

  注：

  fire way：消防车道，意为安全可靠的手段

• Avoid package level state

  Seek to be explicit, reduce coupling, and action at a distance by providing the dependencies a type needs as fields on that type rather than using package variables.

  译：没懂。。。。。

• Simplicity matters

  Simplicity is not a synonym for unsophisticated. Simple doesn’t mean crude, it means readable and maintainable. When it is possible to choose, defer to the simpler solution.

  译：

  简单问题{很禅~~~，两个名词放这里，我也只能这么译了}

  简单不是不成熟的同义词。简单并不意味着粗略，简单意味着可读性和可维护性，当可以去选择时，遵从简单的解决方案。

• Write tests to lock in the behaviour of your package’s API

  Test first or test later, if you shoot for 100% test coverage or are happy with less, regardless your package’s API is your contract with its users. Tests are the guarantees that those contracts are written in. Make sure you test for the behaviour that users can observe and rely on.

• If you think it’s slow, first prove it with a benchmark

  So many crimes against maintainability are committed in the name of performance. Optimisation tears down abstractions, exposes internals, and couples tightly. If you’re choosing to shoulder that cost, ensure it is done for good reason.

• Moderation is a virtue

  Use goroutines, channels, locks, interfaces, embedding, in moderation.

• Maintainability counts

  Clarity, readability, simplicity, are all aspects of maintainability. Can the thing you worked hard to build be maintained after you’re gone? What can you do today to make it easier for those that come after you?

from zen of go