diff options
Diffstat (limited to 'content/pages')
26 files changed, 12778 insertions, 0 deletions
diff --git a/content/pages/_index.md b/content/pages/_index.md new file mode 100644 index 0000000..3d813e3 --- /dev/null +++ b/content/pages/_index.md @@ -0,0 +1,4 @@ +--- +order: '20' +title: Разное +--- diff --git a/content/pages/archive/2007-11-05.md b/content/pages/archive/2007-11-05.md new file mode 100644 index 0000000..ebd0aa3 --- /dev/null +++ b/content/pages/archive/2007-11-05.md @@ -0,0 +1,3 @@ +--- +{} +--- diff --git a/content/pages/archive/2007-11-06.md b/content/pages/archive/2007-11-06.md new file mode 100644 index 0000000..ebd0aa3 --- /dev/null +++ b/content/pages/archive/2007-11-06.md @@ -0,0 +1,3 @@ +--- +{} +--- diff --git a/content/pages/archive/2007-11-08.md b/content/pages/archive/2007-11-08.md new file mode 100644 index 0000000..ebd0aa3 --- /dev/null +++ b/content/pages/archive/2007-11-08.md @@ -0,0 +1,3 @@ +--- +{} +--- diff --git a/content/pages/archive/2007-12-11.md b/content/pages/archive/2007-12-11.md new file mode 100644 index 0000000..ebd0aa3 --- /dev/null +++ b/content/pages/archive/2007-12-11.md @@ -0,0 +1,3 @@ +--- +{} +--- diff --git a/content/pages/archive/2007-12-26.md b/content/pages/archive/2007-12-26.md new file mode 100644 index 0000000..ebd0aa3 --- /dev/null +++ b/content/pages/archive/2007-12-26.md @@ -0,0 +1,3 @@ +--- +{} +--- diff --git a/content/pages/archive/2011-05-10.md b/content/pages/archive/2011-05-10.md new file mode 100644 index 0000000..ebd0aa3 --- /dev/null +++ b/content/pages/archive/2011-05-10.md @@ -0,0 +1,3 @@ +--- +{} +--- diff --git a/content/pages/archive/2011-09-11-1.md b/content/pages/archive/2011-09-11-1.md new file mode 100644 index 0000000..ebd0aa3 --- /dev/null +++ b/content/pages/archive/2011-09-11-1.md @@ -0,0 +1,3 @@ +--- +{} +--- diff --git a/content/pages/archive/2011-09-11-2.md b/content/pages/archive/2011-09-11-2.md new file mode 100644 index 0000000..ebd0aa3 --- /dev/null +++ b/content/pages/archive/2011-09-11-2.md @@ -0,0 +1,3 @@ +--- +{} +--- diff --git a/content/pages/archive/2011-09-11-3.md b/content/pages/archive/2011-09-11-3.md new file mode 100644 index 0000000..ebd0aa3 --- /dev/null +++ b/content/pages/archive/2011-09-11-3.md @@ -0,0 +1,3 @@ +--- +{} +--- diff --git a/content/pages/archive/2011-09-12.md b/content/pages/archive/2011-09-12.md new file mode 100644 index 0000000..ebd0aa3 --- /dev/null +++ b/content/pages/archive/2011-09-12.md @@ -0,0 +1,3 @@ +--- +{} +--- diff --git a/content/pages/archive/2011-09-24.md b/content/pages/archive/2011-09-24.md new file mode 100644 index 0000000..ebd0aa3 --- /dev/null +++ b/content/pages/archive/2011-09-24.md @@ -0,0 +1,3 @@ +--- +{} +--- diff --git a/content/pages/archive/2011-11-20.md b/content/pages/archive/2011-11-20.md new file mode 100644 index 0000000..ebd0aa3 --- /dev/null +++ b/content/pages/archive/2011-11-20.md @@ -0,0 +1,3 @@ +--- +{} +--- diff --git a/content/pages/archive/2011-11-21.md b/content/pages/archive/2011-11-21.md new file mode 100644 index 0000000..ebd0aa3 --- /dev/null +++ b/content/pages/archive/2011-11-21.md @@ -0,0 +1,3 @@ +--- +{} +--- diff --git a/content/pages/archive/_index.md b/content/pages/archive/_index.md new file mode 100644 index 0000000..2a7cea3 --- /dev/null +++ b/content/pages/archive/_index.md @@ -0,0 +1,4 @@ +--- +order: '20' +title: Архив старых постов из WebArchive +--- diff --git a/content/pages/gostyleguide/_index.md b/content/pages/gostyleguide/_index.md new file mode 100644 index 0000000..d38468e --- /dev/null +++ b/content/pages/gostyleguide/_index.md @@ -0,0 +1,6 @@ +--- +order: 10 +title: Go styleguide +--- + +Переводы на русский язык двух самых популярных styleguide по Go. diff --git a/content/pages/gostyleguide/google/_index.md b/content/pages/gostyleguide/google/_index.md new file mode 100644 index 0000000..f28cb04 --- /dev/null +++ b/content/pages/gostyleguide/google/_index.md @@ -0,0 +1,10 @@ +--- +order: 4 +title: Google Go Style Guide +--- + +# Стиль Go + +Оригинал: https://google.github.io/styleguide/go + +<!--more--> diff --git a/content/pages/gostyleguide/google/best-practices.md b/content/pages/gostyleguide/google/best-practices.md new file mode 100644 index 0000000..4fc59b1 --- /dev/null +++ b/content/pages/gostyleguide/google/best-practices.md @@ -0,0 +1,3727 @@ +--- +order: 1 +title: Google Go Style Guide — Лучшие практики +--- + +# Лучшие практики стиля Go (Go Style Best Practices) + +Оригинал: https://google.github.io/styleguide/go/best-practices + +[Обзор](https://neonxp.ru/pages/gostyleguide/google/) | [Руководство](https://neonxp.ru/pages/gostyleguide/google/guide) | [Решения](https://neonxp.ru/pages/gostyleguide/google/decisions) | +[Лучшие практики](https://neonxp.ru/pages/gostyleguide/google/best-practices) + +**Примечание:** Это часть серии документов, описывающих [Стиль Go (Go +Style)](https://neonxp.ru/pages/gostyleguide/google/) в Google. Данный документ **не является ни [нормативным +(normative)](https://neonxp.ru/pages/gostyleguide/google/#normative), ни [каноническим (canonical)](https://neonxp.ru/pages/gostyleguide/google/#canonical)**, +а является вспомогательным документом к [основному руководству по стилю](https://neonxp.ru/pages/gostyleguide/google/guide/). +Подробнее см. [в обзоре](https://neonxp.ru/pages/gostyleguide/google/#about). + +<a id="about"></a> + +## О документе (About) + +В этом документе представлены **рекомендации о том, как наилучшим образом +применять Руководство по стилю Go**. Эти рекомендации предназначены для типичных +ситуаций, возникающих часто, но могут не применяться в каждом случае. По +возможности обсуждаются несколько альтернативных подходов, а также соображения, +которые учитываются при решении о том, когда их применять, а когда нет. + +См. [обзор](https://neonxp.ru/pages/gostyleguide/google/#about) для полного набора документов руководства по стилю. + +<a id="naming"></a> + +## Именование (Naming) + +<a id="function-names"></a> + +### Имена функций и методов + +<a id="function-name-repetition"></a> + +#### Избегайте повторения (Avoid repetition) + +При выборе имени для функции или метода учитывайте контекст, в котором это имя +будет прочитано. Рассмотрите следующие рекомендации, чтобы избежать избыточного +[повторения (repetition)](https://neonxp.ru/pages/gostyleguide/google/decisions/#repetition) в месте вызова (call site): + +* Следующее, как правило, можно опустить в именах функций и методов: + + * Типы входных и выходных данных (если нет конфликта) + * Тип получателя (receiver) метода + * Является ли входной или выходной параметр указателем (pointer) + +* Для функций не следует [повторять имя + пакета](https://neonxp.ru/pages/gostyleguide/google/decisions/#repetitive-with-package). + + ```go + // Плохо: + package yamlconfig + + func ParseYAMLConfig(input string) (*Config, error) + ``` + + ```go + // Хорошо: + package yamlconfig + + func Parse(input string) (*Config, error) + ``` + +* Для методов не следует повторять имя получателя метода. + + ```go + // Плохо: + func (c *Config) WriteConfigTo(w io.Writer) (int64, error) + ``` + + ```go + // Хорошо: + func (c *Config) WriteTo(w io.Writer) (int64, error) + ``` + +* Не повторяйте имена переменных, передаваемых в качестве параметров. + + ```go + // Плохо: + func OverrideFirstWithSecond(dest, source *Config) error + ``` + + ```go + // Хорошо: + func Override(dest, source *Config) error + ``` + +* Не повторяйте имена и типы возвращаемых значений. + + ```go + // Плохо: + func TransformToJSON(input *Config) *jsonconfig.Config + ``` + + ```go + // Хорошо: + func Transform(input *Config) *jsonconfig.Config + ``` + +Когда необходимо устранить неоднозначность между функциями с похожими именами, +допустимо включить дополнительную информацию. + +```go +// Хорошо: +func (c *Config) WriteTextTo(w io.Writer) (int64, error) +func (c *Config) WriteBinaryTo(w io.Writer) (int64, error) +``` + +<a id="function-name-conventions"></a> + +#### Соглашения об именовании (Naming conventions) + +Существуют и другие общие соглашения при выборе имен для функций и методов: + +* Функции, которые что-то возвращают, получают имена, похожие на + существительные. + + ```go + // Хорошо: + func (c *Config) JobName(key string) (value string, ok bool) + ``` + + Следствием этого является то, что имена функций и методов должны [избегать + префикса `Get`](https://neonxp.ru/pages/gostyleguide/google/decisions/#getters). + + ```go + // Плохо: + func (c *Config) GetJobName(key string) (value string, ok bool) + ``` + +* Функции, которые что-то делают, получают имена, похожие на глаголы. + + ```go + // Хорошо: + func (c *Config) WriteDetail(w io.Writer) (int64, error) + ``` + +* Идентичные функции, которые отличаются только типами, включают имя типа в + конце имени. + + ```go + // Хорошо: + func ParseInt(input string) (int, error) + func ParseInt64(input string) (int64, error) + func AppendInt(buf []byte, value int) []byte + func AppendInt64(buf []byte, value int64) []byte + ``` + + Если существует ясная "основная" версия, тип может быть опущен в имени для + этой версии: + + ```go + // Хорошо: + func (c *Config) Marshal() ([]byte, error) + func (c *Config) MarshalText() (string, error) + ``` + +<a id="naming-doubles"></a> + +### Тестовые дубли (Test doubles) и вспомогательные пакеты (helper packages) + +Существует несколько подходов, которые можно применить для [именования] пакетов +и типов, которые предоставляют тестовые вспомогательные средства и особенно +[тестовые дубли (test doubles)]. Тестовым дублем может быть заглушка (stub), +фейк (fake), мок (mock) или шпион (spy). + +Эти примеры в основном используют заглушки. Обновите свои имена соответствующим +образом, если ваш код использует фейки или другой вид тестового дубля. + +[именование]: guide#naming +[тестовые дубли (test doubles)]: + https://abseil.io/resources/swe-book/html/ch13.html#basic_concepts + +Предположим, у вас есть хорошо сфокусированный пакет, предоставляющий +production-код, подобный этому: + +```go +package creditcard + +import ( + "errors" + + "path/to/money" +) + +// ErrDeclined указывает, что эмитент отклонил операцию. +var ErrDeclined = errors.New("creditcard: declined") + +// Card содержит информацию о кредитной карте, такую как эмитент, +// срок действия и лимит. +type Card struct { + // опущено +} + +// Service позволяет выполнять операции с кредитными картами через внешние +// процессинговые системы, такие как списание, авторизация, возврат средств и подписка. +type Service struct { + // опущено +} + +func (s *Service) Charge(c *Card, amount money.Money) error { /* опущено */ } +``` + +<a id="naming-doubles-helper-package"></a> + +#### Создание вспомогательных тестовых пакетов (Creating test helper packages) + +Предположим, вы хотите создать пакет, содержащий тестовые дубли для другого +пакета. Воспользуемся `package creditcard` (из примера выше): + +Один из подходов — создать новый Go-пакет на основе production-пакета для +тестирования. Безопасный выбор — добавить слово `test` к оригинальному имени +пакета ("creditcard" + "test"): + +```go +// Хорошо: +package creditcardtest +``` + +Если явно не указано иное, все примеры в следующих разделах находятся в `package +creditcardtest`. + +<a id="naming-doubles-simple"></a> + +#### Простой случай (Simple case) + +Вы хотите добавить набор тестовых дублей для `Service`. Поскольку `Card` по сути +является простым типом данных, похожим на сообщение Protocol Buffer, он не +требует специальной обработки в тестах, поэтому дубль не нужен. Если вы ожидаете +только тестовые дубли для одного типа (например, `Service`), вы можете +использовать лаконичный подход к именованию дублей: + +```go +// Хорошо: +import ( + "path/to/creditcard" + "path/to/money" +) + +// Stub заглушает creditcard.Service и не предоставляет собственного поведения. +type Stub struct{} + +func (Stub) Charge(*creditcard.Card, money.Money) error { return nil } +``` + +Это строго предпочтительнее, чем выбор имен типа `StubService` или очень плохого +`StubCreditCardService`, потому что базовое имя пакета и его доменные типы +подразумевают, что такое `creditcardtest.Stub`. + +Наконец, если пакет собирается с помощью Bazel, убедитесь, что новое правило +`go_library` для пакета помечено как `testonly`: + +```build +# Хорошо: +go_library( + name = "creditcardtest", + srcs = ["creditcardtest.go"], + deps = [ + ":creditcard", + ":money", + ], + testonly = True, +) +``` + +Приведенный выше подход является общепринятым и будет достаточно хорошо понят +другими инженерами. + +См. также: + +* [Go Tip #42: Authoring a Stub for + Testing](https://google.github.io/styleguide/go/index.html#gotip) + +<a id="naming-doubles-multiple-behaviors"></a> + +#### Несколько вариантов поведения тестового дубля (Multiple test double behaviors) + +Когда одного вида заглушки недостаточно (например, нужна еще одна, которая +всегда завершается ошибкой), мы рекомендуем называть заглушки в соответствии с +поведением, которое они эмулируют. Здесь мы переименовываем `Stub` в +`AlwaysCharges` и вводим новую заглушку `AlwaysDeclines`: + +```go +// Хорошо: +// AlwaysCharges заглушает creditcard.Service и имитирует успех. +type AlwaysCharges struct{} + +func (AlwaysCharges) Charge(*creditcard.Card, money.Money) error { return nil } + +// AlwaysDeclines заглушает creditcard.Service и имитирует отклоненные операции. +type AlwaysDeclines struct{} + +func (AlwaysDeclines) Charge(*creditcard.Card, money.Money) error { + return creditcard.ErrDeclined +} +``` + +<a id="naming-doubles-multiple-types"></a> + +#### Несколько дублей для нескольких типов (Multiple doubles for multiple types) + +Но теперь предположим, что `package creditcard` содержит несколько типов, для +которых стоит создавать дубли, как показано ниже с `Service` и `StoredValue`: + +```go +package creditcard + +type Service struct { + // опущено +} + +type Card struct { + // опущено +} + +// StoredValue управляет кредитными балансами клиентов. Это применяется, когда +// возвращенный товар зачисляется на локальный счет клиента, а не обрабатывается +// эмитентом кредитной карты. По этой причине он реализован как отдельный сервис. +type StoredValue struct { + // опущено +} + +func (s *StoredValue) Credit(c *Card, amount money.Money) error { /* опущено */ } +``` + +В этом случае более явное именование тестовых дублей имеет смысл: + +```go +// Хорошо: +type StubService struct{} + +func (StubService) Charge(*creditcard.Card, money.Money) error { return nil } + +type StubStoredValue struct{} + +func (StubStoredValue) Credit(*creditcard.Card, money.Money) error { return nil } +``` + +<a id="naming-doubles-local-variables"></a> + +#### Локальные переменные в тестах (Local variables in tests) + +Когда переменные в ваших тестах ссылаются на дубли, выберите имя, которое +наиболее четко отличает дубль от других production-типов, исходя из контекста. +Рассмотрим некоторый production-код, который вы хотите протестировать: + +```go +package payment + +import ( + "path/to/creditcard" + "path/to/money" +) + +type CreditCard interface { + Charge(*creditcard.Card, money.Money) error +} + +type Processor struct { + CC CreditCard +} + +var ErrBadInstrument = errors.New("payment: instrument is invalid or expired") + +func (p *Processor) Process(c *creditcard.Card, amount money.Money) error { + if c.Expired() { + return ErrBadInstrument + } + return p.CC.Charge(c, amount) +} +``` + +В тестах тестовой дубль типа "шпион" (spy) для `CreditCard` противопоставляется +production-типам, поэтому добавление префикса к имени может улучшить ясность. + +```go +// Хорошо: +package payment + +import "path/to/creditcardtest" + +func TestProcessor(t *testing.T) { + var spyCC creditcardtest.Spy + proc := &Processor{CC: spyCC} + + // объявления опущены: card и amount + if err := proc.Process(card, amount); err != nil { + t.Errorf("proc.Process(card, amount) = %v, want nil", err) + } + + charges := []creditcardtest.Charge{ + {Card: card, Amount: amount}, + } + + if got, want := spyCC.Charges, charges; !cmp.Equal(got, want) { + t.Errorf("spyCC.Charges = %v, want %v", got, want) + } +} +``` + +Это понятнее, чем когда имя не имеет префикса. + +```go +// Плохо: +package payment + +import "path/to/creditcardtest" + +func TestProcessor(t *testing.T) { + var cc creditcardtest.Spy + + proc := &Processor{CC: cc} + + // объявления опущены: card и amount + if err := proc.Process(card, amount); err != nil { + t.Errorf("proc.Process(card, amount) = %v, want nil", err) + } + + charges := []creditcardtest.Charge{ + {Card: card, Amount: amount}, + } + + if got, want := cc.Charges, charges; !cmp.Equal(got, want) { + t.Errorf("cc.Charges = %v, want %v", got, want) + } +} +``` + +<a id="shadowing"></a> + +### Затенение (Shadowing) + +**Примечание:** Это объяснение использует два неформальных термина, *stomping* и +*shadowing*. Они не являются официальными концепциями в спецификации языка Go. + +Как и во многих языках программирования, в Go есть изменяемые переменные: +присваивание переменной меняет ее значение. + +```go +// Хорошо: +func abs(i int) int { + if i < 0 { + i *= -1 + } + return i +} +``` + +При использовании [короткого объявления переменных (short variable +declarations)] с оператором `:=` в некоторых случаях новая переменная не +создается. Мы можем назвать это *stomping* (затирание). Это допустимо, когда +исходное значение больше не нужно. + +```go +// Хорошо: +// innerHandler — это вспомогательная функция для некоторого обработчика запросов, который сам +// выполняет запросы к другим бэкендам. +func (s *Server) innerHandler(ctx context.Context, req *pb.MyRequest) *pb.MyResponse { + // Безусловно ограничиваем срок действия (deadline) для этой части обработки запроса. + ctx, cancel := context.WithTimeout(ctx, 3*time.Second) + defer cancel() + ctxlog.Info(ctx, "Capped deadline in inner request") + + // Код здесь больше не имеет доступа к оригинальному контексту. + // Это хороший стиль, если при первом написании вы предполагаете, + // что даже по мере роста кода ни одна операция законно не должна + // использовать (возможно, неограниченный) оригинальный контекст, предоставленный вызывающей стороной. + + // ... +} +``` + +Однако будьте осторожны с использованием короткого объявления переменных в новой +области видимости: это вводит новую переменную. Мы можем назвать это *shadowing* +(затенение) исходной переменной. Код после конца блока ссылается на оригинал. +Вот ошибочная попытка условно сократить срок действия (deadline): + +```go +// Плохо: +func (s *Server) innerHandler(ctx context.Context, req *pb.MyRequest) *pb.MyResponse { + // Попытка условно ограничить срок действия. + if *shortenDeadlines { + ctx, cancel := context.WithTimeout(ctx, 3*time.Second) + defer cancel() + ctxlog.Info(ctx, "Capped deadline in inner request") + } + + // ОШИБКА: "ctx" здесь снова означает контекст, предоставленный вызывающей стороной. + // Вышеуказанный ошибочный код скомпилировался, потому что и ctx, и cancel + // использовались внутри оператора if. + + // ... +} +``` + +Правильная версия кода может быть такой: + +```go +// Хорошо: +func (s *Server) innerHandler(ctx context.Context, req *pb.MyRequest) *pb.MyResponse { + if *shortenDeadlines { + var cancel func() + // Обратите внимание на использование простого присваивания, =, а не :=. + ctx, cancel = context.WithTimeout(ctx, 3*time.Second) + defer cancel() + ctxlog.Info(ctx, "Capped deadline in inner request") + } + // ... +} +``` + +В случае, который мы назвали stomping, поскольку нет новой переменной, тип +присваиваемого значения должен совпадать с типом исходной переменной. При +затенении вводится совершенно новая сущность, поэтому она может иметь другой +тип. Намеренное затенение может быть полезной практикой, но вы всегда можете +использовать новое имя, если это улучшает [ясность (clarity)](https://neonxp.ru/pages/gostyleguide/google/guide/#clarity). + +Не рекомендуется использовать переменные с теми же именами, что и у стандартных +пакетов, за исключением очень маленьких областей видимости, потому что это +делает функции и значения из этого пакета недоступными. И наоборот, при выборе +имени для вашего пакета избегайте имен, которые, вероятно, потребуют +[переименования импорта (import renaming)](https://neonxp.ru/pages/gostyleguide/google/decisions/#import-renaming) или +вызовут затенение иначе хороших имен переменных на стороне клиента. + +```go +// Плохо: +func LongFunction() { + url := "https://example.com/" + // Упс, теперь мы не можем использовать net/url в коде ниже. +} +``` + +[короткого объявления переменных (short variable declarations)]: + https://go.dev/ref/spec#Short_variable_declarations + +<a id="util-packages"></a> + +### Пакеты `util` (Util packages) + +Пакеты Go имеют имя, указанное в объявлении `package`, отдельное от пути +импорта. Имя пакета имеет большее значение для читаемости, чем путь. + +Имена пакетов Go должны быть [связаны с тем, что предоставляет +пакет](https://neonxp.ru/pages/gostyleguide/google/decisions/#package-names). Называть пакет просто `util`, `helper`, +`common` или подобным обычно плохой выбор (хотя это может быть использовано как +*часть* имени). Неинформативные имена затрудняют чтение кода, и если они +используются слишком широко, они могут вызывать ненужные [конфликты +импорта](https://neonxp.ru/pages/gostyleguide/google/decisions/#import-renaming). + +Вместо этого подумайте, как будет выглядеть место вызова (callsite). + +```go +// Хорошо: +db := spannertest.NewDatabaseFromFile(...) + +_, err := f.Seek(0, io.SeekStart) + +b := elliptic.Marshal(curve, x, y) +``` + +Вы можете примерно понять, что делает каждая из этих строк, даже не зная списка +импортов (`cloud.google.com/go/spanner/spannertest`, `io` и `crypto/elliptic`). +С менее сфокусированными именами они могли бы читаться так: + +```go +// Плохо: +db := test.NewDatabaseFromFile(...) + +_, err := f.Seek(0, common.SeekStart) + +b := helper.Marshal(curve, x, y) +``` + +<a id="package-size"></a> + +## Размер пакета (Package size) + +Если вы задаетесь вопросом, насколько большими должны быть ваши пакеты Go и +следует ли помещать связанные типы в один пакет или разделять их на разные, +хорошим началом будет [пост в блоге Go об именах пакетов][blog-pkg-names]. +Несмотря на название поста, он не только об именовании. Он содержит полезные +подсказки и ссылается на несколько полезных статей и докладов. + +Вот некоторые другие соображения и примечания. + +Пользователи видят [godoc] для пакета на одной странице, и любые +экспортированные методы типов, предоставляемых пакетом, группируются по их типу. +Godoc также группирует конструкторы вместе с типами, которые они возвращают. +Если *клиентскому коду* (client code) вероятно потребуется, чтобы два значения +разных типов взаимодействовали друг с другом, может быть удобно для пользователя +иметь их в одном пакете. + +Код внутри пакета имеет доступ к неэкспортированным идентификаторам пакета. Если +у вас есть несколько связанных типов, *реализация* которых тесно связана, +размещение их в одном пакете позволяет достичь этой связи без загрязнения +публичного API этими деталями. Хороший тест для этой связи — представить +гипотетического пользователя двух пакетов, где пакеты охватывают тесно связанные +темы: если пользователь должен импортировать оба пакета, чтобы использовать +любой из них хоть сколько-нибудь значимо, обычно правильным решением будет +объединить их вместе. Стандартная библиотека в целом хорошо демонстрирует такую +область видимости (scoping) и слоистость (layering). + +При всем сказанном, помещение всего вашего проекта в один пакет, вероятно, +сделает этот пакет слишком большим. Когда что-то концептуально отличается, +предоставление ему собственного небольшого пакета может облегчить его +использование. Короткое имя пакета, известное клиентам, вместе с именем +экспортированного типа работают вместе, чтобы создать значимый идентификатор: +например, `bytes.Buffer`, `ring.New`. [Пост об именах пакетов][blog-pkg-names] +содержит больше примеров. + +Стиль Go гибок относительно размера файлов, потому что сопровождающие могут +перемещать код внутри пакета из одного файла в другой, не влияя на вызывающую +сторону. Но в качестве общего руководства: обычно не стоит иметь один файл с +тысячами строк или множество крошечных файлов. Нет такого соглашения, как "один +тип — один файл", как в некоторых других языках. Эмпирическое правило: файлы +должны быть достаточно сфокусированными, чтобы сопровождающий мог определить, в +каком файле что-то находится, и достаточно маленькими, чтобы было легко найти +это, когда вы там окажетесь. Стандартная библиотека часто разделяет большие +пакеты на несколько исходных файлов, группируя связанный код по файлам. Исходный +код [пакета `bytes`] является хорошим примером. Пакеты с длинной документацией +могут выбрать выделение одного файла с именем `doc.go`, который содержит +[документацию пакета](https://neonxp.ru/pages/gostyleguide/google/decisions/#package-comments), объявление пакета и больше +ничего, но это не обязательно. + +Внутри кодовой базы Google и в проектах, использующих Bazel, структура каталогов +для кода Go отличается от таковой в open source проектах на Go: вы можете иметь +несколько целей `go_library` в одном каталоге. Хорошей причиной для выделения +каждому пакету собственного каталога является ожидание открытия исходного кода +вашего проекта в будущем. + +Несколько неканонических справочных примеров, чтобы помочь продемонстрировать +эти идеи на практике: + +* маленькие пакеты, содержащие одну связную идею, которая не требует + добавления или удаления чего-либо еще: + + * [пакет `csv`][package `csv`]: кодирование и декодирование данных CSV с + разделением ответственности соответственно между [reader.go] и + [writer.go]. + * [пакет `expvar`][package `expvar`]: "белый ящик" (whitebox) телеметрии + программы, полностью содержащийся в [expvar.go]. + +* пакеты умеренного размера, содержащие одну большую предметную область и + несколько связанных с ней ответственностей: + + * [пакет `flag`][package `flag`]: управление флагами командной строки, + полностью содержащееся в [flag.go]. + +* большие пакеты, которые разделяют несколько тесно связанных предметных + областей по нескольким файлам: + + * [пакет `http`][package `http`]: ядро HTTP: [client.go][http-client], + поддержка HTTP-клиентов; [server.go][http-server], поддержка + HTTP-серверов; [cookie.go], управление куками. + * [пакет `os`][package `os`]: кроссплатформенные абстракции операционной + системы: [exec.go], управление подпроцессами; [file.go], управление + файлами; [tempfile.go], временные файлы. + +См. также: + +* [Пакеты тестовых дублей (Test double packages)](#naming-doubles) +* [Organizing Go Code (Blog Post)] +* [Organizing Go Code (Presentation)] + +[blog-pkg-names]: https://go.dev/blog/package-names +[пакет `bytes`]: https://go.dev/src/bytes/ +[Organizing Go Code (Blog Post)]: https://go.dev/blog/organizing-go-code +[Organizing Go Code (Presentation)]: https://go.dev/talks/2014/organizeio.slide +[пакет `csv`]: https://pkg.go.dev/encoding/csv +[reader.go]: + https://go.googlesource.com/go/+/refs/heads/master/src/encoding/csv/reader.go +[writer.go]: + https://go.googlesource.com/go/+/refs/heads/master/src/encoding/csv/writer.go +[пакет `expvar`]: https://pkg.go.dev/expvar +[expvar.go]: + https://go.googlesource.com/go/+/refs/heads/master/src/expvar/expvar.go +[пакет `flag`]: https://pkg.go.dev/flag +[flag.go]: https://go.googlesource.com/go/+/refs/heads/master/src/flag/flag.go +[godoc]: https://pkg.go.dev/ +[пакет `http`]: https://pkg.go.dev/net/http +[http-client]: + https://go.googlesource.com/go/+/refs/heads/master/src/net/http/client.go +[http-server]: + https://go.googlesource.com/go/+/refs/heads/master/src/net/http/server.go +[cookie.go]: + https://go.googlesource.com/go/+/refs/heads/master/src/net/http/cookie.go +[пакет `os`]: https://pkg.go.dev/os +[exec.go]: https://go.googlesource.com/go/+/refs/heads/master/src/os/exec.go +[file.go]: https://go.googlesource.com/go/+/refs/heads/master/src/os/file.go +[tempfile.go]: + https://go.googlesource.com/go/+/refs/heads/master/src/os/tempfile.go + +<a id="imports"></a> + +## Импорт (Imports) + +<a id="import-protos"></a> + +### Сообщения Protocol Buffer и заглушки (Stubs) + +Импорты библиотек proto обрабатываются иначе, чем стандартные импорты Go, из-за +их межъязыковой природы. Соглашение для переименованных импортов proto основано +на правиле, которое сгенерировало пакет: + +* Суффикс `pb` обычно используется для правил `go_proto_library`. +* Суффикс `grpc` обычно используется для правил `go_grpc_library`. + +Часто используется одно слово, описывающее пакет: + +```go +// Хорошо: +import ( + foopb "path/to/package/foo_service_go_proto" + foogrpc "path/to/package/foo_service_go_grpc" +) +``` + +Следуйте рекомендациям по стилю для [имен +пакетов](https://google.github.io/styleguide/go/decisions#package-names). +Предпочитайте целые слова. Короткие имена хороши, но избегайте неоднозначности. +В случае сомнений используйте имя пакета proto до _go с суффиксом pb: + +```go +// Хорошо: +import ( + pushqueueservicepb "path/to/package/push_queue_service_go_proto" +) +``` + +**Примечание:** Предыдущие рекомендации поощряли очень короткие имена, такие как +"xpb" или даже просто "pb". Новый код должен предпочитать более описательные +имена. Существующий код, использующий короткие имена, не должен использоваться в +качестве примера, но его не нужно менять. + +<a id="import-order"></a> + +### Порядок импорта (Import ordering) + +См. [Go Style Decisions: Группировка импортов](https://neonxp.ru/pages/gostyleguide/google/decisions/.md#import-grouping). + +<a id="error-handling"></a> + +## Обработка ошибок (Error handling) + +В Go [ошибки — это значения (errors are values)]; они создаются кодом и +потребляются кодом. Ошибки могут быть: + +* Преобразованы в диагностическую информацию для отображения человеку +* Использованы сопровождающим +* Интерпретированы конечным пользователем + +Сообщения об ошибках также появляются на самых разных поверхностях, включая +сообщения журнала (log messages), дампы ошибок и отрисованные пользовательские +интерфейсы. + +Код, который обрабатывает (производит или потребляет) ошибки, должен делать это +осознанно. Может возникнуть соблазн проигнорировать или слепо распространить +возвращаемое значение ошибки. Однако всегда стоит подумать, находится ли текущая +функция в стеке вызовов в наилучшей позиции для обработки ошибки. Это обширная +тема, и трудно дать категоричные рекомендации. Используйте свое суждение, но +учитывайте следующие соображения: + +* Создавая значение ошибки, решите, придавать ли ему какую-либо + [структуру](#error-structure). +* Обрабатывая ошибку, рассмотрите возможность [добавления + информации](#error-extra-info), которая есть у вас, но которой может не быть + у вызывающей и/или вызываемой стороны. +* См. также рекомендации по [логированию ошибок](#error-logging). + +Хотя обычно нецелесообразно игнорировать ошибку, разумным исключением из этого +является оркестрация связанных операций, где часто только первая ошибка полезна. +Пакет [`errgroup`] предоставляет удобную абстракцию для группы операций, которые +могут завершиться ошибкой или быть отменены как группа. + +[ошибки — это значения (errors are values)]: + https://go.dev/blog/errors-are-values +[`errgroup`]: https://pkg.go.dev/golang.org/x/sync/errgroup + +См. также: + +* [Effective Go об ошибках](https://go.dev/doc/effective_go#errors) +* [Пост в блоге Go об ошибках](https://go.dev/blog/go1.13-errors) +* [Пакет `errors`](https://pkg.go.dev/errors) +* [Пакет + `upspin.io/errors`](https://commandcenter.blogspot.com/2017/12/error-handling-in-upspin.html) +* [GoTip #89: When to Use Canonical Status Codes as + Errors](https://google.github.io/styleguide/go/index.html#gotip) +* [GoTip #48: Error Sentinel + Values](https://google.github.io/styleguide/go/index.html#gotip) +* [GoTip #13: Designing Errors for + Checking](https://google.github.io/styleguide/go/index.html#gotip) + +<a id="error-structure"></a> + +### Структура ошибок (Error structure) + +Если вызывающим сторонам необходимо анализировать ошибку (например, различать +различные условия ошибки), придайте значению ошибки структуру, чтобы это можно +было сделать программно, а не заставлять вызывающую сторону выполнять +сопоставление строк. Этот совет применим как к production-коду, так и к тестам, +которые заботятся о разных условиях ошибок. + +Простейшие структурированные ошибки — это непараметризованные глобальные +значения. + +```go +type Animal string + +var ( + // ErrDuplicate возникает, если это животное уже было замечено. + ErrDuplicate = errors.New("duplicate") + + // ErrMarsupial возникает, потому что у нас аллергия на сумчатых за пределами Австралии. + // Извините. + ErrMarsupial = errors.New("marsupials are not supported") +) + +func process(animal Animal) error { + switch { + case seen[animal]: + return ErrDuplicate + case marsupial(animal): + return ErrMarsupial + } + seen[animal] = true + // ... + return nil +} +``` + +Вызывающая сторона может просто сравнить возвращенное значение ошибки функции с +одним из известных значений ошибок: + +```go +// Хорошо: +func handlePet(...) { + switch err := process(an); err { + case ErrDuplicate: + return fmt.Errorf("feed %q: %v", an, err) + case ErrMarsupial: + // Попробуем восстановиться с помощью друга. + alternate = an.BackupAnimal() + return handlePet(..., alternate, ...) + } +} +``` + +Выше используются сторожевые (sentinel) значения, где ошибка должна быть равна +(в смысле `==`) ожидаемому значению. Во многих случаях это вполне адекватно. +Если `process` возвращает обернутые ошибки (wrapped errors) (обсуждается ниже), +вы можете использовать [`errors.Is`]. + +```go +// Хорошо: +func handlePet(...) { + switch err := process(an); { + case errors.Is(err, ErrDuplicate): + return fmt.Errorf("feed %q: %v", an, err) + case errors.Is(err, ErrMarsupial): + // ... + } +} +``` + +Не пытайтесь различать ошибки на основе их строковой формы. (См. [GoTip #13: +Designing Errors for +Checking](https://google.github.io/styleguide/go/index.html#gotip) для получения +дополнительной информации.) + +```go +// Плохо: +func handlePet(...) { + err := process(an) + if regexp.MatchString(`duplicate`, err.Error()) {...} + if regexp.MatchString(`marsupial`, err.Error()) {...} +} +``` + +Если в ошибке есть дополнительная информация, которая нужна вызывающей стороне +программно, ее, в идеале, следует представить структурно. Например, тип +[`os.PathError`] документирован так, что помещает путь к операции, завершившейся +неудачей, в поле структуры, к которому вызывающая сторона может легко получить +доступ. + +Могут использоваться и другие структуры ошибок, например, структура проекта, +содержащая код ошибки и строку с деталями. [Пакет `status`][status] — +распространенная инкапсуляция; если вы выбираете этот подход (вы не обязаны это +делать), используйте [канонические коды (canonical codes)]. См. [GoTip #89: +When to Use Canonical Status Codes as +Errors](https://google.github.io/styleguide/go/index.html#gotip) чтобы понять, +является ли использование кодов статуса правильным выбором. + +[`os.PathError`]: https://pkg.go.dev/os#PathError +[`errors.Is`]: https://pkg.go.dev/errors#Is +[`errors.As`]: https://pkg.go.dev/errors#As +[`package cmp`]: https://pkg.go.dev/github.com/google/go-cmp/cmp +[status]: https://pkg.go.dev/google.golang.org/grpc/status +[канонические коды (canonical codes)]: + https://pkg.go.dev/google.golang.org/grpc/codes + +<a id="error-extra-info"></a> + +### Добавление информации к ошибкам (Adding information to errors) + +Добавляя информацию к ошибкам, избегайте избыточной информации, которую уже +предоставляет лежащая в основе ошибка. Пакет `os`, например, уже включает +информацию о пути в своих ошибках. + +```go +// Хорошо: +if err := os.Open("settings.txt"); err != nil { + return fmt.Errorf("launch codes unavailable: %v", err) +} + +// Вывод: +// +// launch codes unavailable: open settings.txt: no such file or directory +``` + +Здесь "launch codes unavailable" добавляет конкретный смысл ошибке `os.Open`, +релевантный для контекста текущей функции, без дублирования информации о пути к +файлу. + +```go +// Плохо: +if err := os.Open("settings.txt"); err != nil { + return fmt.Errorf("could not open settings.txt: %v", err) +} + +// Вывод: +// +// could not open settings.txt: open settings.txt: no such file or directory +``` + +Не добавляйте аннотацию, если ее единственная цель — указать на сбой без +добавления новой информации. Наличие ошибки достаточно передает сбой вызывающей +стороне. + +```go +// Плохо: +return fmt.Errorf("failed: %v", err) // просто верните err вместо этого +``` + +[Выбор между `%v` и `%w` при оборачивании ошибок (wrapping +errors)](https://go.dev/blog/go1.13-errors#whether-to-wrap) с помощью +`fmt.Errorf` — это тонкое решение, которое значительно влияет на то, как ошибки +распространяются, обрабатываются, проверяются и документируются в вашем +приложении. Основной принцип — сделать значения ошибок полезными для их +наблюдателей, будь то люди или код. + +1. **`%v` для простой аннотации или новой ошибки** + + Глагол `%v` — это ваш универсальный инструмент для строкового форматирования + любого значения Go, включая ошибки. При использовании с `fmt.Errorf` он + встраивает строковое представление ошибки (то, что возвращает ее метод + `Error()`) в новое значение ошибки, отбрасывая любую структурированную + информацию из исходной ошибки. Примеры использования `%v`: + + * Добавление интересного, не избыточного контекста: как в примере выше. + + * Логирование или отображение ошибок: Когда основная цель — представить + удобочитаемое сообщение об ошибке в журналах или пользователю, и вы не + планируете, чтобы вызывающая сторона программно проверяла ошибку с + помощью `errors.Is` или `errors.As` (Примечание: `errors.Unwrap` здесь, + как правило, не рекомендуется, так как он не обрабатывает множественные + ошибки (multi-errors)). + + * Создание новых, независимых ошибок: Иногда необходимо преобразовать + ошибку в новое сообщение об ошибке, тем самым скрывая специфику исходной + ошибки. Эта практика особенно полезна на границах систем, включая, + помимо прочего, RPC, IPC и хранилища, где мы переводим + доменно-специфичные ошибки в каноническое пространство ошибок. + + ```go + // Хорошо: + func (*FortuneTeller) SuggestFortune(context.Context, *pb.SuggestionRequest) (*pb.SuggestionResponse, error) { + // ... + if err != nil { + return nil, fmt.Errorf("couldn't find fortune database: %v", err) + } + } + ``` + + Мы также могли бы явно аннотировать RPC код `Internal` в примере выше. + + ```go + // Хорошо: + import ( + "google.golang.org/grpc/codes" + "google.golang.org/grpc/status" + ) + + func (*FortuneTeller) SuggestFortune(context.Context, *pb.SuggestionRequest) (*pb.SuggestionResponse, error) { + // ... + if err != nil { + // Или используйте fmt.Errorf с глаголом %w, если намеренно оборачиваете ошибку, + // которую вызывающая сторона должна развернуть (unwrap). + return nil, status.Errorf(codes.Internal, "couldn't find fortune database", status.ErrInternal) + } + } + ``` + +1. **`%w` (wrap) для программной проверки и цепочки ошибок (error chaining)** + + Глагол `%w` специально предназначен для оборачивания ошибок (error + wrapping). Он создает новую ошибку, которая предоставляет метод `Unwrap()`, + позволяя вызывающим сторонам программно проверять цепочку ошибок с помощью + `errors.Is` и `errors.As`. Примеры использования `%w`: + + * Добавление контекста с сохранением исходной ошибки для программной + проверки: Это основной случай использования во вспомогательных функциях + (helpers) вашего приложения. Вы хотите обогатить ошибку дополнительным + контекстом (например, какая операция выполнялась, когда она завершилась + неудачей), но при этом позволить вызывающей стороне проверить, является + ли лежащая в основе ошибка конкретной сторожевой ошибкой или типом. + + ```go + // Хорошо: + func (s *Server) internalFunction(ctx context.Context) error { + // ... + if err != nil { + return fmt.Errorf("couldn't find remote file: %w", err) + } + } + ``` + + Это позволяет функции более высокого уровня выполнить `errors.Is(err, + fs.ErrNotExist)`, даже если исходная ошибка была обернута. + + В точках, где ваша система взаимодействует с внешними системами, такими + как RPC, IPC или хранилище, часто лучше переводить доменно-специфичные + ошибки в стандартизированное пространство ошибок (например, коды статуса + gRPC), а не просто оборачивать исходную ошибку с помощью `%w`. Клиента + обычно не волнует точная внутренняя ошибка файловой системы; их волнует + канонический результат (например, `Internal`, `NotFound`, + `PermissionDenied`). + + * Когда вы явно документируете и тестируете лежащие в основе ошибки, + которые вы раскрываете: Если API вашего пакета гарантирует, что + определенные лежащие в основе ошибки могут быть развернуты и проверены + вызывающими сторонами (например, "эта функция может вернуть + `ErrInvalidConfig`, обернутый в более общую ошибку"), то `%w` уместен. + Это становится частью контракта вашего пакета. + +См. также: + +* [Соглашения по документации ошибок (Error Documentation + Conventions)](#documentation-conventions-errors) +* [Пост в блоге об оборачивании ошибок](https://blog.golang.org/go1.13-errors) + +<a id="error-percent-w"></a> + +### Размещение `%w` в ошибках (Placement of %w in errors) + +Предпочитайте размещать `%w` в конце строки ошибки *если* вы используете +[оборачивание ошибок (error wrapping)](https://go.dev/blog/go1.13-errors) с +глаголом форматирования `%w`. + +Ошибки могут быть обернуты с помощью глагола `%w` или путем помещения их в +[структурированную +ошибку](https://google.github.io/styleguide/go/index.html#gotip), которая +реализует `Unwrap() error` (например, +[`fs.PathError`](https://pkg.go.dev/io/fs#PathError)). + +Обернутые ошибки образуют цепочки ошибок (error chains): каждый новый слой +обертывания добавляет новую запись в начало цепочки ошибок. Цепочку ошибок можно +обойти с помощью метода `Unwrap() error`. Например: + +```go +err1 := fmt.Errorf("err1") +err2 := fmt.Errorf("err2: %w", err1) +err3 := fmt.Errorf("err3: %w", err2) +``` + +Это формирует цепочку ошибок следующего вида: + +```mermaid +flowchart LR + err3 == err3 wraps err2 ==> err2; + err2 == err2 wraps err1 ==> err1; +``` + +Независимо от того, где размещен глагол `%w`, возвращаемая ошибка всегда +представляет начало цепочки ошибок, а `%w` — это следующий дочерний элемент. +Аналогично, `Unwrap() error` всегда обходит цепочку ошибок от самой новой к +самой старой ошибке. + +Однако размещение глагола `%w` влияет на то, печатается ли цепочка ошибок от +самой новой к самой старой, от самой старой к самой новой или ни то, ни другое: + +```go +// Хорошо: +err1 := fmt.Errorf("err1") +err2 := fmt.Errorf("err2: %w", err1) +err3 := fmt.Errorf("err3: %w", err2) +fmt.Println(err3) // err3: err2: err1 +// err3 — это цепочка ошибок от самой новой к самой старой, которая печатается от самой новой к самой старой. +``` + +```go +// Плохо: +err1 := fmt.Errorf("err1") +err2 := fmt.Errorf("%w: err2", err1) +err3 := fmt.Errorf("%w: err3", err2) +fmt.Println(err3) // err1: err2: err3 +// err3 — это цепочка ошибок от самой новой к самой старой, которая печатается от самой старой к самой новой. +``` + +```go +// Плохо: +err1 := fmt.Errorf("err1") +err2 := fmt.Errorf("err2-1 %w err2-2", err1) +err3 := fmt.Errorf("err3-1 %w err3-2", err2) +fmt.Println(err3) // err3-1 err2-1 err1 err2-2 err3-2 +// err3 — это цепочка ошибок от самой новой к самой старой, которая печатается ни от самой новой к самой старой, +// ни от самой старой к самой новой. +``` + +Поэтому, чтобы текст ошибки отражал структуру цепочки ошибок, предпочитайте +размещать глагол `%w` в конце в форме `[...]: %w`. + +<a id="error-logging"></a> + +### Логирование ошибок (Logging errors) + +Иногда функциям необходимо сообщить внешней системе об ошибке, не передавая ее +своим вызывающим сторонам. Логирование — очевидный выбор здесь; но будьте +внимательны к тому, что и как вы логируете. + +* Как и [хорошие сообщения о неудачных тестах (good test failure messages)], + сообщения журнала должны четко выражать, что пошло не так, и помогать + сопровождающему, включая соответствующую информацию для диагностики + проблемы. + +* Избегайте дублирования. Если вы возвращаете ошибку, обычно лучше не + логировать ее самостоятельно, а позволить вызывающей стороне обработать ее. + Вызывающая сторона может выбрать логирование ошибки или, возможно, + ограничить частоту логирования с помощью [`rate.Sometimes`]. Другие варианты + включают попытку восстановления или даже [остановку программы]. В любом + случае, предоставление контроля вызывающей стороне помогает избежать спама в + журналах. + + Однако обратной стороной этого подхода является то, что любое логирование + записывается с использованием координат строк вызывающей стороны. + +* Будьте осторожны с [PII]. Многие приемники журналов (log sinks) не являются + подходящими местами назначения для конфиденциальной информации конечных + пользователей. + +* Используйте `log.Error` скупо. Логирование уровня ERROR вызывает сброс + (flush) и является более дорогостоящим, чем более низкие уровни логирования. + Это может серьезно повлиять на производительность вашего кода. Принимая + решение между уровнями error и warning, учитывайте лучшую практику: + сообщения на уровне error должны быть actionable (то есть требовать + действий), а не просто "более серьезными", чем warning. + +* Внутри Google у нас есть системы мониторинга, которые можно настроить для + более эффективного оповещения, чем просто запись в файл журнала в надежде, + что кто-то его заметит. Это похоже, но не идентично стандартной библиотеке + [пакету `expvar`]. + +[хорошие сообщения о неудачных тестах (good test failure messages)]: + https://google.github.io/styleguide/go/decisions#useful-test-failures +[остановку программы]: #checks-and-panics +[`rate.Sometimes`]: https://pkg.go.dev/golang.org/x/time/rate#Sometimes +[PII]: https://en.wikipedia.org/wiki/Personal_data +[пакет `expvar`]: https://pkg.go.dev/expvar + +<a id="vlog"></a> + +#### Пользовательские уровни детализации (Custom verbosity levels) + +Используйте детальное логирование ([`log.V`]) с пользой. Детальное логирование +может быть полезно для разработки и трассировки. Установление соглашения об +уровнях детализации может быть полезным. Например: + +* Записывайте небольшое количество дополнительной информации на `V(1)` +* Трассируйте больше информации на `V(2)` +* Выводите большие внутренние состояния на `V(3)` + +Чтобы минимизировать стоимость детального логирования, вы должны убедиться, что +случайно не вызываете дорогие функции, даже когда `log.V` выключен. `log.V` +предлагает два API. Более удобный из них несет риск этих случайных затрат. В +случае сомнений используйте немного более многословный стиль. + +```go +// Хорошо: +for _, sql := range queries { + log.V(1).Infof("Handling %v", sql) + if log.V(2) { + log.Infof("Handling %v", sql.Explain()) + } + sql.Run(...) +} +``` + +```go +// Плохо: +// sql.Explain вызывается даже когда это сообщение не печатается. +log.V(2).Infof("Handling %v", sql.Explain()) +``` + +[`log.V`]: https://pkg.go.dev/github.com/golang/glog#V + +<a id="program-init"></a> + +### Инициализация программы (Program initialization) + +Ошибки инициализации программы (например, неправильные флаги и конфигурация) +должны передаваться вверх в `main`, который должен вызвать `log.Exit` с ошибкой, +объясняющей, как исправить ошибку. В этих случаях `log.Fatal` обычно не следует +использовать, потому что трассировка стека, указывающая на проверку, вряд ли +будет так полезна, как сгенерированное человеком, actionable сообщение. + +<a id="checks-and-panics"></a> + +### Проверки программы и паники (Program checks and panics) + +Как указано в [решении против паник (decision against panics)], стандартная +обработка ошибок должна быть структурирована вокруг возвращаемых значений +ошибок. Библиотеки должны предпочитать возвращать ошибку вызывающей стороне, а +не завершать программу, особенно для временных ошибок. + +Иногда необходимо выполнить проверку согласованности (consistency check) +инварианта и завершить программу, если он нарушен. Как правило, это делается +только в том случае, если сбой проверки инварианта означает, что внутреннее +состояние стало невосстановимым. Наиболее надежный способ сделать это в кодовой +базе Google — вызвать `log.Fatal`. Использование `panic` в этих случаях +ненадежно, потому что возможно, что отложенные (deferred) функции заблокируют +или еще больше повредят внутреннее или внешнее состояние. + +Аналогично, сопротивляйтесь искушению восстановить паники (recover panics), +чтобы избежать сбоев, так как это может привести к распространению поврежденного +состояния. Чем дальше вы от паники, тем меньше вы знаете о состоянии программы, +которая может удерживать блокировки или другие ресурсы. Затем программа может +развить другие неожиданные режимы сбоев, которые могут еще больше затруднить +диагностику проблемы. Вместо того чтобы пытаться обрабатывать неожиданные паники +в коде, используйте инструменты мониторинга для выявления неожиданных сбоев и +исправляйте связанные ошибки с высоким приоритетом. + +**Примечание:** Стандартный [`net/http` server] нарушает этот совет и +восстанавливает паники из обработчиков запросов. Консенсус среди опытных +инженеров Go заключается в том, что это была историческая ошибка. Если вы +исследуете журналы серверов приложений на других языках, часто можно найти +большие трассировки стека, которые остаются необработанными. Избегайте этой +ловушки в своих серверах. + +[решении против паник (decision against panics)]: + https://google.github.io/styleguide/go/decisions#dont-panic +[`net/http` server]: https://pkg.go.dev/net/http#Server + +<a id="when-to-panic"></a> + +### Когда использовать panic (When to panic) + +Стандартная библиотека вызывает panic при неправильном использовании API. +Например, [`reflect`] вызывает panic во многих случаях, когда значение доступно +таким образом, что предполагает его неправильную интерпретацию. Это аналогично +паникам на ошибки ядра языка, такие как доступ к элементу среза вне его границ. +Проверка кода и тесты должны обнаруживать такие ошибки, которые не ожидаются в +production-коде. Эти паники действуют как проверки инвариантов, которые не +зависят от библиотеки, поскольку стандартная библиотека не имеет доступа к +[уровневому пакету `log`], который используется в кодовой базе Google. + +[`reflect`]: https://pkg.go.dev/reflect +[уровневому пакету `log`]: decisions#logging + +Другой случай, когда паники могут быть полезны, хотя и нечасто, — это внутренняя +деталь реализации пакета, которая всегда имеет соответствующее восстановление +(recover) в цепочке вызовов. Парсеры и подобные глубоко вложенные, тесно +связанные внутренние группы функций могут выиграть от такого дизайна, где +проталкивание возвратов ошибок добавляет сложность без ценности. + +Ключевой атрибут этого дизайна заключается в том, что эти **паники никогда не +должны выходить за границы пакета** и не должны быть частью API пакета. Обычно +это достигается с помощью функции верхнего уровня с отложенным вызовом +(deferred), которая использует `recover` для преобразования распространенной +паники в возвращаемую ошибку на публичной границе API. Это требует, чтобы код, +который вызывает panic и восстанавливается, отличал паники, которые код вызывает +сам, от тех, которые он не вызывает: + +```go +// Хорошо: +type syntaxError struct { + msg string +} + +func parseInt(in string) int { + n, err := strconv.Atoi(in) + if err != nil { + panic(&syntaxError{"not a valid integer"}) + } +} + +func Parse(in string) (_ *Node, err error) { + defer func() { + if p := recover(); p != nil { + sErr, ok := p.(*syntaxError) + if !ok { + panic(p) // Распространяем panic, поскольку он находится вне области нашего кода. + } + err = fmt.Errorf("syntax error: %v", sErr.msg) + } + }() + ... // Парсим входные данные, вызывая parseInt внутри для парсинга целых чисел +} +``` + +> **Предупреждение:** Код, использующий этот шаблон, должен позаботиться об +> управлении любыми ресурсами, связанными с кодом, запущенным в таких разделах, +> управляемых defer (например, закрыть, освободить или разблокировать). +> +> См.: [Go Tip #81: Avoiding Resource Leaks in API Design] + +Паника также используется, когда компилятор не может идентифицировать +недостижимый код, например, при использовании функции типа `log.Fatal`, которая +не вернется: + +```go +// Хорошо: +func answer(i int) string { + switch i { + case 42: + return "yup" + case 54: + return "base 13, huh" + default: + log.Fatalf("Sorry, %d is not the answer.", i) + panic("unreachable") + } +} +``` + +[Не вызывайте функции `log` до того, как флаги будут +распарсены.](https://pkg.go.dev/github.com/golang/glog#pkg-overview) Если вы +должны завершиться в функции инициализации пакета (в `init` или +["must"-функции](https://neonxp.ru/pages/gostyleguide/google/decisions/#must-functions)), panic допустима вместо вызова +фатального логирования. + +См. также: + +* [Handling panics](https://go.dev/ref/spec#Handling_panics) и [Run-time + Panics](https://go.dev/ref/spec#Run_time_panics) в спецификации языка +* [Defer, Panic, and Recover](https://go.dev/blog/defer-panic-and-recover) +* [On the uses and misuses of panics in + Go](https://eli.thegreenplace.net/2018/on-the-uses-and-misuses-of-panics-in-go/) + +[Go Tip #81: Avoiding Resource Leaks in API Design]: + https://google.github.io/styleguide/go/index.html#gotip + +<a id="documentation"></a> + +## Документация (Documentation) + +<a id="documentation-conventions"></a> + +### Соглашения (Conventions) + +Этот раздел дополняет раздел [комментариев (commentary)] в документе решений. + +Код на Go, который документирован в знакомом стиле, легче читать и менее +вероятно, что его будут использовать неправильно, по сравнению с тем, что плохо +задокументировано или не задокументировано вовсе. Запускаемые [примеры +(examples)] появляются в Godoc и Code Search и являются отличным способом +объяснить, как использовать ваш код. + +[комментариев (commentary)]: decisions#commentary +[примеры (examples)]: decisions#examples + +<a id="documentation-conventions-params"></a> + +#### Параметры и конфигурация (Parameters and configuration) + +Не каждый параметр должен быть перечислен в документации. Это относится к: + +* параметрам функций и методов +* полям структур (struct fields) +* API для опций (options) + +Документируйте подверженные ошибкам или неочевидные поля и параметры, объясняя, +почему они интересны. + +В следующем фрагменте выделенный комментарий добавляет мало полезной информации +для читателя: + +```go +// Плохо: +// Sprintf форматирует в соответствии со спецификатором формата и возвращает результирующую строку. +// +// format — это формат, а data — данные для интерполяции. +func Sprintf(format string, data ...any) string +``` + +Однако этот фрагмент демонстрирует сценарий кода, похожий на предыдущий, где +комментарий вместо этого говорит что-то неочевидное или существенно полезное для +читателя: + +```go +// Хорошо: +// Sprintf форматирует в соответствии со спецификатором формата и возвращает результирующую строку. +// +// Предоставленные данные используются для интерполяции строки формата. Если данные не соответствуют +// ожидаемым глаголам формата или количество данных не удовлетворяет спецификации формата, +// функция будет встраивать предупреждения об ошибках форматирования в выходную строку, как описано +// в разделе "Format errors" выше. +func Sprintf(format string, data ...any) string +``` + +Учитывайте вашу вероятную аудиторию при выборе того, что документировать и на +какую глубину. Сопровождающие, новички в команде, внешние пользователи и даже вы +сами через шесть месяцев могут оценить немного другую информацию, отличную от +той, что у вас на уме, когда вы впервые начинаете писать документацию. + +См. также: + +* [GoTip #41: Identify Function Call Parameters] +* [GoTip #51: Patterns for Configuration] + +[GoTip #41: Identify Function Call Parameters]: + https://google.github.io/styleguide/go/index.html#gotip +[GoTip #51: Patterns for Configuration]: + https://google.github.io/styleguide/go/index.html#gotip + +<a id="documentation-conventions-contexts"></a> + +#### Контексты (Contexts) + +Подразумевается, что отмена (cancellation) аргумента контекста прерывает +функцию, которой он предоставлен. Если функция может возвращать ошибку, по +соглашению это `ctx.Err()`. + +Этот факт не нужно повторять: + +```go +// Плохо: +// Run выполняет рабочий цикл (run loop) воркера. +// +// Метод будет обрабатывать работу до отмены контекста и соответственно возвращает ошибку. +func (Worker) Run(ctx context.Context) error +``` + +Поскольку это подразумевается, следующее лучше: + +```go +// Хорошо: +// Run выполняет рабочий цикл воркера. +func (Worker) Run(ctx context.Context) error +``` + +Когда поведение контекста отличается или неочевидно, его следует прямо +задокументировать, если верно любое из следующего. + +* Функция возвращает ошибку, отличную от `ctx.Err()`, когда контекст отменен: + + ```go + // Хорошо: + // Run выполняет рабочий цикл воркера. + // + // Если контекст отменен, Run возвращает nil ошибку. + func (Worker) Run(ctx context.Context) error + ``` + +* Функция имеет другие механизмы, которые могут ее прервать или повлиять на + время жизни: + + ```go + // Хорошо: + // Run выполняет рабочий цикл воркера. + // + // Run обрабатывает работу до отмены контекста или вызова Stop. + // Отмена контекста обрабатывается асинхронно внутри: run может вернуться до того, + // как вся работа остановится. Метод Stop является синхронным и ожидает завершения + // всех операций из рабочего цикла. Используйте Stop для плавного завершения работы. + func (Worker) Run(ctx context.Context) error + + func (Worker) Stop() + ``` + +* Функция имеет особые ожидания относительно времени жизни контекста, его + происхождения (lineage) или прикрепленных значений (attached values): + + ```go + // Хорошо: + // NewReceiver начинает получать сообщения, отправленные в указанную очередь. + // Контекст не должен иметь дедлайна (deadline). + func NewReceiver(ctx context.Context) *Receiver + + // Principal возвращает человеко-читаемое имя стороны, совершившей вызов. + // Контекст должен иметь прикрепленное к нему значение из security.NewContext. + func Principal(ctx context.Context) (name string, ok bool) + ``` + + **Предупреждение:** Избегайте разработки API, которые предъявляют такие + требования (например, отсутствие дедлайнов у контекстов) от своих вызывающих + сторон. Вышеприведенное — лишь пример того, как это задокументировать, если + этого нельзя избежать, а не одобрение такого шаблона. + +<a id="documentation-conventions-concurrency"></a> + +#### Параллелизм (Concurrency) + +Пользователи Go предполагают, что концептуально доступные только для чтения +операции безопасны для параллельного использования и не требуют дополнительной +синхронизации. + +Дополнительное замечание о параллелизме можно безопасно удалить в этой Godoc: + +```go +// Хорошо: +// Len возвращает количество байт непрочитанной части буфера; +// b.Len() == len(b.Bytes()). +// +// Безопасно для вызова несколькими горутинами одновременно. +func (*Buffer) Len() int +``` + +Однако мутирующие операции не считаются безопасными для параллельного +использования и требуют, чтобы пользователь учитывал синхронизацию. + +Аналогично, дополнительное замечание о параллелизме можно безопасно удалить +здесь: + +```go +// Хорошо: +// Grow увеличивает емкость буфера. +// +// Не безопасно для вызова несколькими горутинами одновременно. +func (*Buffer) Grow(n int) +``` + +Настоятельно рекомендуется документировать, если верно любое из следующего. + +* Непонятно, является ли операция доступной только для чтения или мутирующей: + + ```go + // Хорошо: + package lrucache + + // Lookup возвращает данные, связанные с ключом, из кэша. + // + // Эта операция не безопасна для параллельного использования. + func (*Cache) Lookup(key string) (data []byte, ok bool) + ``` + + Почему? При попадании в кэш (cache hit) при поиске ключа внутреннее + состояние LRU-кэша мутирует. Как это реализовано, может быть неочевидно для + всех читателей. + +* Синхронизация предоставляется API: + + ```go + // Хорошо: + package fortune_go_proto + + // NewFortuneTellerClient возвращает *rpc.Client для сервиса FortuneTeller. + // Безопасно для одновременного использования несколькими горутинами. + func NewFortuneTellerClient(cc *rpc.ClientConn) *FortuneTellerClient + ``` + + Почему? Stubby предоставляет синхронизацию. + + **Примечание:** Если API является типом и API предоставляет синхронизацию в + целом, по соглашению только определение типа документирует семантику. + +* API потребляет пользовательские реализации типов или интерфейсов, и + потребитель интерфейса имеет особые требования к параллелизму: + + ```go + // Хорошо: + package health + + // Watcher сообщает о состоянии здоровья некоторой сущности (обычно серверной службы). + // + // Методы Watcher безопасны для одновременного использования несколькими горутинами. + type Watcher interface { + // Watch отправляет true на переданный канал, когда статус Watcher изменился. + Watch(changed chan<- bool) (unwatch func()) + + // Health возвращает nil, если за которой следят сущность здорова, или + // ненулевую ошибку, объясняющую, почему сущность нездорова. + Health() error + } + ``` + + Почему? Является ли API безопасным для использования несколькими горутинами + — это часть его контракта. + +<a id="documentation-conventions-cleanup"></a> + +#### Очистка (Cleanup) + +Документируйте любые явные требования к очистке, которые есть у API. В противном +случае вызывающие стороны будут использовать API неправильно, что приведет к +утечкам ресурсов и другим возможным ошибкам. + +Указывайте очистки, которые зависят от вызывающей стороны: + +```go +// Хорошо: +// NewTicker возвращает новый Ticker, содержащий канал, который будет отправлять +// текущее время на канал после каждого тика. +// +// Вызовите Stop, чтобы освободить ресурсы, связанные с Ticker, когда закончите. +func NewTicker(d Duration) *Ticker + +func (*Ticker) Stop() +``` + +Если может быть неясно, как очистить ресурсы, объясните, как: + +```go +// Хорошо: +// Get выполняет GET к указанному URL. +// +// Когда err равен nil, resp всегда содержит ненулевой resp.Body. +// Вызывающая сторона должна закрыть resp.Body, когда закончит читать из него. +// +// resp, err := http.Get("http://example.com/") +// if err != nil { +// // обработать ошибку +// } +// defer resp.Body.Close() +// body, err := io.ReadAll(resp.Body) +func (c *Client) Get(url string) (resp *Response, err error) +``` + +См. также: + +* [GoTip #110: Don’t Mix Exit With Defer] + +[GoTip #110: Don’t Mix Exit With Defer]: + https://google.github.io/styleguide/go/index.html#gotip + +<a id="documentation-conventions-errors"></a> + +#### Ошибки (Errors) + +Документируйте значимые сторожевые значения ошибок (error sentinel values) или +типы ошибок, которые ваши функции возвращают вызывающим сторонам, чтобы +вызывающие стороны могли предвидеть, какие типы условий они могут обработать в +своем коде. + +```go +// Хорошо: +package os + +// Read читает до len(b) байт из File и сохраняет их в b. Он возвращает +// количество прочитанных байт и любую встреченную ошибку. +// +// При достижении конца файла Read возвращает 0, io.EOF. +func (*File) Read(b []byte) (n int, err error) { +``` + +Когда функция возвращает определенный тип ошибки, правильно укажите, является ли +ошибка указателем (pointer receiver) или нет: + +```go +// Хорошо: +package os + +type PathError struct { + Op string + Path string + Err error +} + +// Chdir меняет текущий рабочий каталог на указанный каталог. +// +// Если есть ошибка, она будет типа *PathError. +func Chdir(dir string) error { +``` + +Документирование того, являются ли возвращаемые значения указателями, позволяет +вызывающим сторонам правильно сравнивать ошибки с помощью [`errors.Is`], +[`errors.As`] и [`package cmp`]. Это связано с тем, что не указатель +(non-pointer value) не эквивалентен указателю (pointer value). + +**Примечание:** В примере `Chdir` тип возвращаемого значения записан как +`error`, а не `*PathError`, из-за [как работают нулевые значения интерфейса (nil +interface values)](https://go.dev/doc/faq#nil_error). + +Документируйте общие соглашения об ошибках в [документации +пакета](https://neonxp.ru/pages/gostyleguide/google/decisions/#package-comments), когда поведение применимо к большинству +ошибок, встречающихся в пакете: + +```go +// Хорошо: +// Пакет os предоставляет независимый от платформы интерфейс к функциям операционной системы. +// +// Часто доступно больше информации внутри ошибки. Например, если вызов, принимающий имя файла, +// завершается неудачей, такой как Open или Stat, ошибка будет включать имя файла, которое +// не удалось, когда она печатается, и будет иметь тип *PathError, который может быть распакован +// для получения дополнительной информации. +package os +``` + +Вдумчивое применение этих подходов может добавить [дополнительную информацию к +ошибкам](#error-extra-info) без особых усилий и помочь вызывающим сторонам +избежать добавления избыточных аннотаций. + +См. также: + +* [Go Tip #106: Error Naming + Conventions](https://google.github.io/styleguide/go/index.html#gotip) +* [Go Tip #89: When to Use Canonical Status Codes as + Errors](https://google.github.io/styleguide/go/index.html#gotip) + +<a id="documentation-preview"></a> + +### Предварительный просмотр (Preview) + +Go имеет [сервер +документации](https://pkg.go.dev/golang.org/x/pkgsite/cmd/pkgsite). +Рекомендуется предварительно просматривать документацию, которую производит ваш +код, как до, так и во время процесса ревью кода. Это помогает проверить, что +[форматирование godoc] отображается правильно. + +[форматирование godoc]: #godoc-formatting + +<a id="godoc-formatting"></a> + +### Форматирование Godoc (Godoc formatting) + +[Godoc] предоставляет специальный синтаксис для [форматирования документации]. + +* Требуется пустая строка для разделения абзацев: + + ```go + // Хорошо: + // LoadConfig читает конфигурацию из указанного файла. + // + // См. some/shortlink для подробностей о формате файла конфигурации. + ``` + +* Файлы тестов могут содержать [запускаемые примеры (runnable examples)], + которые появляются прикрепленными к соответствующей документации в godoc: + + ```go + // Хорошо: + func ExampleConfig_WriteTo() { + cfg := &Config{ + Name: "example", + } + if err := cfg.WriteTo(os.Stdout); err != nil { + log.Exitf("Failed to write config: %s", err) + } + // Output: + // { + // "name": "example" + // } + } + ``` + +* Отступ строк на два дополнительных пробела форматирует их буквально + (verbatim): + + ```go + // Хорошо: + // Update выполняет функцию в атомарной транзакции. + // + // Обычно это используется с анонимной TransactionFunc: + // + // if err := db.Update(func(state *State) { state.Foo = bar }); err != nil { + // //... + // } + ``` + + Однако обратите внимание, что часто может быть более уместно поместить код в + запускаемый пример, а не включать его в комментарий. + + Это буквальное форматирование может быть использовано для форматирования, не + родного для godoc, такого как списки и таблицы: + + ```go + // Хорошо: + // LoadConfig читает конфигурацию из указанного файла. + // + // LoadConfig обрабатывает следующие ключи особым образом: + // "import" заставит эту конфигурацию наследовать из указанного файла. + // "env" если присутствует, будет заполнен системным окружением. + ``` + +* Одна строка, которая начинается с заглавной буквы, не содержит знаков + препинания, кроме скобок и запятых, и за которой следует другой абзац, + форматируется как заголовок: + + ```go + // Хорошо: + // Следующая строка форматируется как заголовок. + // + // Использование заголовков + // + // Заголовки поставляются с автоматически сгенерированными якорными тегами для удобного связывания. + ``` + +[Godoc]: https://pkg.go.dev/ +[форматирования документации]: https://go.dev/doc/comment +[запускаемые примеры (runnable examples)]: decisions#examples + +<a id="signal-boost"></a> + +### Усиление сигнала (Signal boosting) + +Иногда строка кода выглядит как нечто обычное, но на самом деле это не так. Один +из лучших примеров этого — проверка `err == nil` (поскольку `err != nil` +встречается гораздо чаще). Следующие две условные проверки трудно различить: + +```go +// Хорошо: +if err := doSomething(); err != nil { + // ... +} +``` + +```go +// Плохо: +if err := doSomething(); err == nil { + // ... +} +``` + +Вы можете вместо этого "усилить" сигнал условного оператора, добавив +комментарий: + +```go +// Хорошо: +if err := doSomething(); err == nil { // если ошибки НЕТ + // ... +} +``` + +Комментарий привлекает внимание к различию в условном операторе. + +<a id="vardecls"></a> + +## Объявление переменных (Variable declarations) + +<a id="vardeclinitialization"></a> + +### Инициализация (Initialization) + +Для единообразия предпочитайте `:=` вместо `var` при инициализации новой +переменной ненулевым значением. + +```go +// Хорошо: +i := 42 +``` + +```go +// Плохо: +var i = 42 +``` + +<a id="vardeclzero"></a> + +### Объявление переменных с нулевыми значениями (Declaring variables with zero values) + +Следующие объявления используют [нулевое значение (zero value)]: + +```go +// Хорошо: +var ( + coords Point + magic [4]byte + primes []int +) +``` + +[нулевое значение (zero value)]: https://golang.org/ref/spec#The_zero_value + +Вы должны объявлять значения, используя нулевое значение, когда хотите передать +пустое значение, которое **готово к использованию позже**. Использование +составных литералов (composite literals) с явной инициализацией может быть +громоздким: + +```go +// Плохо: +var ( + coords = Point{X: 0, Y: 0} + magic = [4]byte{0, 0, 0, 0} + primes = []int(nil) +) +``` + +Распространенное применение объявления с нулевым значением — когда переменная +используется как выход при демаршалинге (unmarshalling): + +```go +// Хорошо: +var coords Point +if err := json.Unmarshal(data, &coords); err != nil { +``` + +Также допустимо использовать нулевое значение в следующей форме, когда вам нужна +переменная типа указателя: + +```go +// Хорошо: +msg := new(pb.Bar) // или "&pb.Bar{}" +if err := proto.Unmarshal(data, msg); err != nil { +``` + +Если в вашей структуре нужна блокировка (lock) или другое поле, которое [не +должно копироваться](https://neonxp.ru/pages/gostyleguide/google/decisions/#copying), вы можете сделать его типом значения +(value type), чтобы воспользоваться преимуществами инициализации нулевым +значением. Это означает, что содержащий тип теперь должен передаваться по +указателю, а не по значению. Методы этого типа должны принимать +получатели-указатели (pointer receivers). + +```go +// Хорошо: +type Counter struct { + // Это поле не обязательно должно быть "*sync.Mutex". Однако + // пользователи теперь должны передавать *Counter объекты между собой, а не Counter. + mu sync.Mutex + data map[string]int64 +} + +// Обратите внимание, что это должен быть получатель-указатель, чтобы предотвратить копирование. +func (c *Counter) IncrementBy(name string, n int64) +``` + +Допустимо использовать типы значений для локальных переменных составных типов +(таких как структуры и массивы), даже если они содержат такие некопируемые поля. +Однако, если составной тип возвращается функцией, или если все обращения к нему +в конечном итоге требуют взятия адреса, предпочтительнее объявить переменную как +тип указателя с самого начала. Аналогично, сообщения protobuf должны объявляться +как типы указателей. + +```go +// Хорошо: +func NewCounter(name string) *Counter { + c := new(Counter) // "&Counter{}" тоже подходит. + registerCounter(name, c) + return c +} + +var msg = new(pb.Bar) // или "&pb.Bar{}". +``` + +Это потому, что `*pb.Something` удовлетворяет [`proto.Message`], а +`pb.Something` — нет. + +```go +// Плохо: +func NewCounter(name string) *Counter { + var c Counter + registerCounter(name, &c) + return &c +} + +var msg = pb.Bar{} +``` + +[`proto.Message`]: https://pkg.go.dev/google.golang.org/protobuf/proto#Message + +> **Важно:** Типы map должны быть явно инициализированы перед тем, как их можно +> будет изменять. Однако чтение из map с нулевым значением вполне допустимо. +> +> Для типов map и slice, если код особенно чувствителен к производительности и +> если вы заранее знаете размеры, см. раздел [подсказки по размеру (size +> hints)](#vardeclsize). + +<a id="vardeclcomposite"></a> + +### Составные литералы (Composite literals) + +Следующие объявления являются [составными литералами (composite literal)]: + +```go +// Хорошо: +var ( + coords = Point{X: x, Y: y} + magic = [4]byte{'I', 'W', 'A', 'D'} + primes = []int{2, 3, 5, 7, 11} + captains = map[string]string{"Kirk": "James Tiberius", "Picard": "Jean-Luc"} +) +``` + +Вы должны объявлять значение с помощью составного литерала, когда знаете +начальные элементы или члены. + +В отличие от этого, использование составных литералов для объявления пустых +значений или значений без членов может быть визуально шумным по сравнению с +[инициализацией нулевым значением](#vardeclzero). + +Когда вам нужен указатель на нулевое значение, у вас есть два варианта: пустые +составные литералы и `new`. Оба варианта допустимы, но ключевое слово `new` +может служить напоминанием читателю, что если бы потребовалось ненулевое +значение, составной литерал не сработал бы: + +```go +// Хорошо: +var ( + buf = new(bytes.Buffer) // непустые Buffers инициализируются конструкторами. + msg = new(pb.Message) // непустые proto сообщения инициализируются билдерами или установкой полей по одному. +) +``` + +[составные литералы (composite literal)]: + https://golang.org/ref/spec#Composite_literals + +<a id="vardeclsize"></a> + +### Подсказки по размеру (Size hints) + +Следующие объявления используют подсказки по размеру, чтобы предварительно +выделить емкость: + +```go +// Хорошо: +var ( + // Предпочтительный размер буфера для целевой файловой системы: st_blksize. + buf = make([]byte, 131072) + // Обычно обрабатывается до 8-10 элементов за запуск (16 — безопасное предположение). + q = make([]Node, 0, 16) + // Каждый шард обрабатывает shardSize (обычно 32000+) элементов. + seen = make(map[string]bool, shardSize) +) +``` + +Подсказки по размеру и предварительное выделение — важные шаги **в сочетании с +эмпирическим анализом кода и его интеграций**, для создания производительного и +ресурсоэффективного кода. + +Большинству кода не нужны подсказки по размеру или предварительное выделение, и +он может позволить среде выполнения увеличивать срез или карту по мере +необходимости. Допустимо предварительно выделять память, когда окончательный +размер известен (например, при преобразовании между map и срезом), но это не +является требованием читаемости и может не стоить загромождения в простых +случаях. + +**Предупреждение:** Предварительное выделение больше памяти, чем нужно, может +тратить память в парке (fleet) или даже вредить производительности. В случае +сомнений см. [GoTip #3: Benchmarking Go Code] и по умолчанию используйте +[инициализацию нулевым значением](#vardeclzero) или [объявление составным +литералом](#vardeclcomposite). + +[GoTip #3: Benchmarking Go Code]: + https://google.github.io/styleguide/go/index.html#gotip + +<a id="decl-chan"></a> + +### Направление каналов (Channel direction) + +Указывайте [направление канала (channel direction)] там, где это возможно. + +```go +// Хорошо: +// sum вычисляет сумму всех значений. Она читает из канала до тех пор, +// пока канал не закроется. +func sum(values <-chan int) int { + // ... +} +``` + +Это предотвращает случайные ошибки программирования, которые возможны без +спецификации: + +```go +// Плохо: +func sum(values chan int) (out int) { + for v := range values { + out += v + } + // values уже должен быть закрыт для достижения этого кода, что означает, + // что второе закрытие вызовет панику. + close(values) +} +``` + +Когда направление указано, компилятор перехватывает простые ошибки, подобные +этой. Это также помогает передать меру владения (ownership) типу. + +См. также доклад Брайана Миллса "Rethinking Classical Concurrency Patterns": +[слайды][rethinking-concurrency-slides] [видео][rethinking-concurrency-video]. + +[rethinking-concurrency-slides]: + https://drive.google.com/file/d/1nPdvhB0PutEJzdCq5ms6UI58dp50fcAN/view?usp=sharing +[rethinking-concurrency-video]: https://www.youtube.com/watch?v=5zXAHh5tJqQ +[направление канала (channel direction)]: https://go.dev/ref/spec#Channel_types + +<a id="funcargs"></a> + +## Списки аргументов функций (Function argument lists) + +Не позволяйте сигнатуре функции становиться слишком длинной. По мере добавления +большего количества параметров в функцию роль отдельных параметров становится +менее ясной, а соседние параметры одного типа становится легче спутать. Функции +с большим количеством аргументов менее запоминаемы и их труднее читать в месте +вызова. + +При проектировании API рассмотрите возможность разделения высоконастраиваемой +функции, сигнатура которой становится сложной, на несколько более простых. Они +могут использовать общую (неэкспортируемую) реализацию, если это необходимо. + +Если функции требуется много входных данных, рассмотрите возможность введения +[структуры опций (option struct)] для некоторых аргументов или использование +более продвинутой техники [вариативных опций (variadic options)]. Основным +критерием выбора стратегии должно быть то, как выглядит вызов функции во всех +ожидаемых случаях использования. + +Приведенные ниже рекомендации в первую очередь применяются к экспортированным +API, к которым предъявляются более высокие стандарты, чем к неэкспортированным. +Эти методы могут быть не нужны для вашего случая использования. Используйте свое +суждение и балансируйте между принципами [ясности (clarity)] и [наименьшей +механизации (least mechanism)]. + +См. также: [Go Tip #24: Use Case-Specific +Constructions](https://google.github.io/styleguide/go/index.html#gotip) + +[структуры опций (option struct)]: #option-structure +[вариативных опций (variadic options)]: #variadic-options +[ясности (clarity)]: guide#clarity +[наименьшей механизации (least mechanism)]: guide#least-mechanism + +<a id="option-structure"></a> + +### Структура опций (Option structure) + +Структура опций (option structure) — это тип struct, который собирает некоторые +или все аргументы функции или метода, а затем передается в качестве последнего +аргумента функции или методу. (Структура должна быть экспортирована только если +она используется в экспортированной функции.) + +Использование структуры опций имеет ряд преимуществ: + +* Литерал структуры включает как поля, так и значения для каждого аргумента, + что делает их самодокументированными и затрудняет их перестановку. +* Несущественные или "значения по умолчанию" поля могут быть опущены. +* Вызывающие стороны могут совместно использовать структуру опций и писать + вспомогательные функции для работы с ней. +* Структуры обеспечивают более чистую документацию для каждого поля, чем + аргументы функций. +* Структуры опций могут расти со временем без влияния на места вызова. + +Вот пример функции, которую можно улучшить: + +```go +// Плохо: +func EnableReplication(ctx context.Context, config *replicator.Config, primaryRegions, readonlyRegions []string, replicateExisting, overwritePolicies bool, replicationInterval time.Duration, copyWorkers int, healthWatcher health.Watcher) { + // ... +} +``` + +Функция выше может быть переписана со структурой опций следующим образом: + +```go +// Хорошо: +type ReplicationOptions struct { + Config *replicator.Config + PrimaryRegions []string + ReadonlyRegions []string + ReplicateExisting bool + OverwritePolicies bool + ReplicationInterval time.Duration + CopyWorkers int + HealthWatcher health.Watcher +} + +func EnableReplication(ctx context.Context, opts ReplicationOptions) { + // ... +} +``` + +Затем функцию можно вызвать в другом пакете: + +```go +// Хорошо: +func foo(ctx context.Context) { + // Сложный вызов: + storage.EnableReplication(ctx, storage.ReplicationOptions{ + Config: config, + PrimaryRegions: []string{"us-east1", "us-central2", "us-west3"}, + ReadonlyRegions: []string{"us-east5", "us-central6"}, + OverwritePolicies: true, + ReplicationInterval: 1 * time.Hour, + CopyWorkers: 100, + HealthWatcher: watcher, + }) + + // Простой вызов: + storage.EnableReplication(ctx, storage.ReplicationOptions{ + Config: config, + PrimaryRegions: []string{"us-east1", "us-central2", "us-west3"}, + }) +} +``` + +**Примечание:** [Контексты никогда не включаются в структуры +опций](https://neonxp.ru/pages/gostyleguide/google/decisions/#contexts). + +Этот вариант часто предпочтителен, когда применимо одно из следующих условий: + +* Все вызывающие стороны должны указать одну или несколько опций. +* Большому количеству вызывающих сторон необходимо предоставить множество + опций. +* Опции используются совместно несколькими функциями, которые будет вызывать + пользователь. + +<a id="variadic-options"></a> + +### Вариативные опции (Variadic options) + +Используя вариативные опции, создаются экспортированные функции, которые +возвращают замыкания (closures), которые могут быть переданы в [вариативный +(`...`) параметр] функции. Функция принимает в качестве параметров значения +опции (если есть), а возвращаемое замыкание принимает изменяемую ссылку (обычно +указатель на тип struct), которая будет обновлена на основе входных данных. + +[вариативный (`...`) параметр]: + https://golang.org/ref/spec#Passing_arguments_to_..._parameters + +Использование вариативных опций может предоставить ряд преимуществ: + +* Опции не занимают места в месте вызова, когда конфигурация не нужна. +* Опции все еще являются значениями, поэтому вызывающие стороны могут делиться + ими, писать вспомогательные функции и накапливать их. +* Опции могут принимать несколько параметров (например, + `cartesian.Translate(dx, dy int) TransformOption`). +* Функции опций могут возвращать именованный тип, чтобы группировать опции + вместе в godoc. +* Пакеты могут разрешать (или запрещать) сторонним пакетам определять (или + запрещать определение) свои собственные опции. + +**Примечание:** Использование вариативных опций требует значительного количества +дополнительного кода (см. следующий пример), поэтому их следует использовать +только тогда, когда преимущества перевешивают накладные расходы. + +Вот пример функции, которую можно улучшить: + +```go +// Плохо: +func EnableReplication(ctx context.Context, config *placer.Config, primaryCells, readonlyCells []string, replicateExisting, overwritePolicies bool, replicationInterval time.Duration, copyWorkers int, healthWatcher health.Watcher) { + ... +} +``` + +Пример выше может быть переписан с вариативными опциями следующим образом: + +```go +// Хорошо: +type replicationOptions struct { + readonlyCells []string + replicateExisting bool + overwritePolicies bool + replicationInterval time.Duration + copyWorkers int + healthWatcher health.Watcher +} + +// ReplicationOption настраивает EnableReplication. +type ReplicationOption func(*replicationOptions) + +// ReadonlyCells добавляет дополнительные ячейки, которые дополнительно +// должны содержать реплики только для чтения данных. +// +// Передача этой опции несколько раз добавит дополнительные +// ячейки только для чтения. +// +// По умолчанию: нет +func ReadonlyCells(cells ...string) ReplicationOption { + return func(opts *replicationOptions) { + opts.readonlyCells = append(opts.readonlyCells, cells...) + } +} + +// ReplicateExisting контролирует, будут ли файлы, уже существующие в +// первичных ячейках, реплицированы. В противном случае только недавно добавленные +// файлы будут кандидатами на репликацию. +// +// Повторная передача этой опции перезапишет предыдущие значения. +// +// По умолчанию: false +func ReplicateExisting(enabled bool) ReplicationOption { + return func(opts *replicationOptions) { + opts.replicateExisting = enabled + } +} + +// ... другие опции ... + +// DefaultReplicationOptions управляют значениями по умолчанию перед +// применением опций, переданных в EnableReplication. +var DefaultReplicationOptions = []ReplicationOption{ + OverwritePolicies(true), + ReplicationInterval(12 * time.Hour), + CopyWorkers(10), +} + +func EnableReplication(ctx context.Context, config *placer.Config, primaryCells []string, opts ...ReplicationOption) { + var options replicationOptions + for _, opt := range DefaultReplicationOptions { + opt(&options) + } + for _, opt := range opts { + opt(&options) + } +} +``` + +Затем функцию можно вызвать в другом пакете: + +```go +// Хорошо: +func foo(ctx context.Context) { + // Сложный вызов: + storage.EnableReplication(ctx, config, []string{"po", "is", "ea"}, + storage.ReadonlyCells("ix", "gg"), + storage.OverwritePolicies(true), + storage.ReplicationInterval(1*time.Hour), + storage.CopyWorkers(100), + storage.HealthWatcher(watcher), + ) + + // Простой вызов: + storage.EnableReplication(ctx, config, []string{"po", "is", "ea"}) +} +``` + +Предпочитайте этот вариант, когда применимо большинство из следующего: + +* Большинству вызывающих сторон не нужно указывать никакие опции. +* Большинство опций используется редко. +* Существует большое количество опций. +* Опции требуют аргументов. +* Опции могут завершиться неудачей или быть установлены неправильно (в этом + случае функция опции возвращает `error`). +* Опции требуют большого количества документации, которую трудно уместить в + структуре. +* Пользователи или другие пакеты могут предоставлять пользовательские опции. + +Опции в этом стиле должны принимать параметры, а не использовать наличие +(presence) для сигнализации своего значения; последнее может значительно +усложнить динамическое составление аргументов. Например, двоичные настройки +должны принимать логическое значение (например, `rpc.FailFast(enable bool)` +предпочтительнее, чем `rpc.EnableFailFast()`). Перечисляемая опция должна +принимать перечисляемую константу (например, `log.Format(log.Capacitor)` +предпочтительнее, чем `log.CapacitorFormat()`). Альтернатива значительно +усложняет жизнь пользователям, которые должны программно выбирать, какие опции +передавать; такие пользователи вынуждены изменять фактический состав параметров, +а не просто изменять аргументы опций. Не предполагайте, что все пользователи +будут статически знать полный набор опций. + +Как правило, опции должны обрабатываться по порядку. Если возникает конфликт или +если некумулятивная опция передается несколько раз, должен побеждать последний +аргумент. + +Параметр функции опции в этом шаблоне обычно не экспортируется, чтобы ограничить +определение опций только самим пакетом. Это хороший вариант по умолчанию, хотя +могут быть случаи, когда уместно позволить другим пакетам определять опции. + +См. [оригинальный пост в блоге Роба Пайка] и [доклад Дейва Ченея] для более +глубокого изучения того, как эти опции могут быть использованы. + +[оригинальный пост в блоге Роба Пайка]: + http://commandcenter.blogspot.com/2014/01/self-referential-functions-and-design.html +[доклад Дейва Ченея]: + https://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis + +<a id="complex-clis"></a> + +## Сложные интерфейсы командной строки (Complex command-line interfaces) + +Некоторые программы хотят предоставить пользователям богатый интерфейс командной +строки, включающий подкоманды. Например, `kubectl create`, `kubectl run` и +многие другие подкоманды предоставляются программой `kubectl`. Существует по +крайней мере следующие общеупотребительные библиотеки для достижения этого. + +Если у вас нет предпочтений или другие соображения равны, рекомендуется +[subcommands], поскольку она самая простая и с ней легко работать правильно. +Однако, если вам нужны другие функции, которые она не предоставляет, выберите +один из других вариантов. + +* **[cobra]** + + * Соглашение о флагах: getopt + * Распространена за пределами кодовой базы Google. + * Много дополнительных функций. + * Подводные камни в использовании (см. ниже). + +* **[subcommands]** + + * Соглашение о флагах: Go + * Проста и с ней легко работать правильно. + * Рекомендуется, если вам не нужны дополнительные функции. + +**Предупреждение**: функции команд cobra должны использовать `cmd.Context()` для +получения контекста, а не создавать свой собственный корневой контекст с помощью +`context.Background`. Код, использующий пакет subcommands, уже получает +правильный контекст как параметр функции. + +Вы не обязаны помещать каждую подкоманду в отдельный пакет, и часто в этом нет +необходимости. Применяйте те же соображения о границах пакетов, что и в любой +кодовой базе Go. Если ваш код может использоваться как библиотека и как бинарный +файл, обычно полезно отделить CLI-код от библиотеки, делая CLI просто еще одним +из ее клиентов. (Это не специфично для CLI с подкомандами, но упоминается здесь, +потому что это частое место, где это возникает.) + +[subcommands]: https://pkg.go.dev/github.com/google/subcommands +[cobra]: https://pkg.go.dev/github.com/spf13/cobra + +<a id="tests"></a> + +## Тесты (Tests) + +<a id="test-functions"></a> + +### Оставляйте тестирование функции `Test` + +<!-- Примечание для сопровождающих: Этот раздел пересекается с decisions#assert и +decisions#mark-test-helpers. Цель не в том, чтобы повторять информацию, а +в том, чтобы иметь одно место, которое суммирует различие, о котором часто +задумываются новички в языке. --> + +Go различает "тестовые помощники (test helpers)" и "помощники утверждений +(assertion helpers)": + +* **Тестовые помощники** — это функции, которые выполняют задачи настройки или + очистки. Все сбои, которые происходят в тестовых помощниках, ожидаемо + являются сбоями окружения (а не тестируемого кода) — например, когда + тестовая база данных не может быть запущена, потому что на этой машине + больше нет свободных портов. Для таких функций часто уместно вызывать + `t.Helper`, чтобы [пометить их как тестовый помощник]. См. [обработку ошибок + в тестовых помощниках] для более подробной информации. + +* **Помощники утверждений** — это функции, которые проверяют правильность + системы и завершают тест с ошибкой, если ожидание не выполняется. Помощники + утверждений [не считаются идиоматичными] в Go. + +Цель теста — сообщить о условиях прохождения/непрохождения тестируемого кода. +Идеальное место для завершения теста с ошибкой — внутри самой функции `Test`, +так как это обеспечивает ясность [сообщений об ошибках] и логики теста. + +[пометить их как тестовый помощник]: decisions#mark-test-helpers +[обработку ошибок в тестовых помощниках]: #test-helper-error-handling +[не считаются идиоматичными]: decisions#assert +[сообщений об ошибках]: decisions#useful-test-failures + +По мере роста вашего тестового кода может стать необходимым вынести некоторую +функциональность в отдельные функции. Стандартные соображения программной +инженерии все еще применяются, поскольку *тестовый код — это все еще код*. Если +функциональность не взаимодействует с тестовым фреймворком, то применяются все +обычные правила. Однако, когда общий код взаимодействует с фреймворком, +необходимо соблюдать осторожность, чтобы избежать распространенных подводных +камней, которые могут привести к неинформативным сообщениям об ошибках и +неудобным в поддержке тестам. + +Если многим отдельным тестовым случаям требуется одна и та же логика валидации, +организуйте тест одним из следующих способов вместо использования помощников +утверждений или сложных функций валидации: + +* Встройте логику (и валидацию, и завершение с ошибкой) в функцию `Test`, даже + если это повторяется. Это лучше всего работает в простых случаях. +* Если входные данные похожи, рассмотрите возможность объединения их в + [табличный тест (table-driven test)], сохраняя логику встроенной в цикл. Это + помогает избежать повторения, сохраняя валидацию и завершение с ошибкой в + `Test`. +* Если есть несколько вызывающих сторон, которым нужна одна и та же функция + валидации, но табличные тесты не подходят (обычно потому, что входные данные + недостаточно просты или валидация требуется как часть последовательности + операций), организуйте функцию валидации так, чтобы она возвращала значение + (обычно `error`), а не принимала параметр `testing.T` и использовала его для + завершения теста с ошибкой. Используйте логику внутри `Test`, чтобы решить, + завершать ли тест с ошибкой, и предоставить [полезные сообщения об ошибках + теста]. Вы также можете создать тестовые помощники для выноса общего + шаблонного кода настройки. + +Дизайн, описанный в последнем пункте, сохраняет ортогональность. Например, +[пакет `cmp`] не предназначен для завершения тестов с ошибкой, а для сравнения +(и вычисления различий) значений. Поэтому ему не нужно знать о контексте, в +котором было сделано сравнение, поскольку вызывающая сторона может предоставить +его. Если ваш общий тестовый код предоставляет `cmp.Transformer` для вашего типа +данных, это часто может быть самым простым дизайном. Для других проверок +рассмотрите возможность возврата значения `error`. + +```go +// Хорошо: +// polygonCmp возвращает cmp.Option, которое приравнивает объекты геометрии s2 +// с некоторой небольшой ошибкой с плавающей точкой. +func polygonCmp() cmp.Option { + return cmp.Options{ + cmp.Transformer("polygon", func(p *s2.Polygon) []*s2.Loop { return p.Loops() }), + cmp.Transformer("loop", func(l *s2.Loop) []s2.Point { return l.Vertices() }), + cmpopts.EquateApprox(0.00000001, 0), + cmpopts.EquateEmpty(), + } +} + +func TestFenceposts(t *testing.T) { + // Это тест для вымышленной функции Fenceposts, которая рисует забор + // вокруг некоторого объекта Place. Детали не важны, за исключением того, + // что результат — это некоторый объект, имеющий геометрию s2 (github.com/golang/geo/s2) + got := Fencepost(tomsDiner, 1*meter) + if diff := cmp.Diff(want, got, polygonCmp()); diff != "" { + t.Errorf("Fencepost(tomsDiner, 1m) returned unexpected diff (-want+got):\n%v", diff) + } +} + +func FuzzFencepost(f *testing.F) { + // Фаззинг-тест (https://go.dev/doc/fuzz) для того же. + + f.Add(tomsDiner, 1*meter) + f.Add(school, 3*meter) + + f.Fuzz(func(t *testing.T, geo Place, padding Length) { + got := Fencepost(geo, padding) + // Простая эталонная реализация: не используется в prod, но проста для + // понимания и поэтому полезна для проверки в случайных тестах. + reference := slowFencepost(geo, padding) + + // Во фаззинг-тесте входные и выходные данные могут быть большими, поэтому + // не беспокойтесь о печати diff. cmp.Equal достаточно. + if !cmp.Equal(got, reference, polygonCmp()) { + t.Errorf("Fencepost returned wrong placement") + } + }) +} +``` + +Функция `polygonCmp` агностична относительно того, как ее вызывают; она не +принимает конкретный тип входных данных и не контролирует, что делать, если два +объекта не совпадают. Поэтому больше вызывающих сторон могут использовать ее. + +**Примечание:** Существует аналогия между тестовыми помощниками и обычным +библиотечным кодом. Код в библиотеках обычно [не должен вызывать panic] за +редкими исключениями; код, вызываемый из теста, не должен останавливать тест, +если нет [смысла продолжать]. + +[табличный тест (table-driven test)]: decisions#table-driven-tests +[полезные сообщения об ошибках теста]: decisions#useful-test-failures +[пакет `cmp`]: https://pkg.go.dev/github.com/google/go-cmp/cmp +[не должен вызывать panic]: decisions#dont-panic +[смысла продолжать]: #t-fatal + +<a id="test-validation-apis"></a> + +### Проектирование расширяемых API валидации (Designing extensible validation APIs) + +Большая часть советов о тестировании в руководстве по стилю касается +тестирования вашего собственного кода. Этот раздел о том, как предоставить +средства для других людей тестировать код, который они пишут, чтобы убедиться, +что он соответствует требованиям вашей библиотеки. + +<a id="test-validation-apis-what"></a> + +#### Приемочное тестирование (Acceptance testing) + +Такое тестирование называется [приемочным тестированием (acceptance testing)]. +Предпосылка такого тестирования заключается в том, что человек, использующий +тест, не знает всех деталей того, что происходит в тесте; он просто передает +входные данные в тестовое средство, чтобы оно выполнило работу. Это можно +рассматривать как форму [инверсии управления (inversion of control)]. + +В типичном тесте Go тестовая функция контролирует поток программы, и +рекомендации [без утверждений (no assert)](https://neonxp.ru/pages/gostyleguide/google/decisions/#assert) и [тестовые +функции](#test-functions) побуждают вас сохранять это так. Этот раздел +объясняет, как создавать поддержку для таких тестов способом, согласующимся со +стилем Go. + +Прежде чем углубляться в "как", рассмотрим пример из [`io/fs`], приведенный +ниже: + +```go +type FS interface { + Open(name string) (File, error) +} +``` + +Хотя существуют хорошо известные реализации `fs.FS`, от разработчика Go может +потребоваться создать свою. Чтобы помочь проверить правильность пользовательской +реализации `fs.FS`, была предоставлена универсальная библиотека в +[`testing/fstest`] под названием [`fstest.TestFS`]. Этот API рассматривает +реализацию как черный ящик (blackbox), чтобы убедиться, что она соблюдает самые +основные части контракта `io/fs`. + +[приемочным тестированием (acceptance testing)]: + https://en.wikipedia.org/wiki/Acceptance_testing +[инверсии управления (inversion of control)]: + https://en.wikipedia.org/wiki/Inversion_of_control +[`io/fs`]: https://pkg.go.dev/io/fs +[`testing/fstest`]: https://pkg.go.dev/testing/fstest +[`fstest.TestFS`]: https://pkg.go.dev/testing/fstest#TestFS + +<a id="test-validation-apis-writing"></a> + +#### Написание приемочного теста (Writing an acceptance test) + +Теперь, когда мы знаем, что такое приемочный тест и почему вы можете его +использовать, давайте рассмотрим создание приемочного теста для `package chess`, +пакета, используемого для симуляции шахматных игр. Пользователи `chess` должны +реализовать интерфейс `chess.Player`. Эти реализации — основное, что мы будем +проверять. Наш приемочный тест касается того, делает ли реализация игрока +легальные ходы, а не того, являются ли ходы умными. + +1. Создайте новый пакет для поведения валидации, [обычно + именуемый](#naming-doubles-helper-package) добавлением слова `test` к имени + пакета (например, `chesstest`). + +1. Создайте функцию, которая выполняет валидацию, принимая тестируемую + реализацию в качестве аргумента и проверяя ее: + + ```go + // ExercisePlayer тестирует реализацию Player за один ход на доске. + // Сама доска выборочно проверяется на разумность и правильность. + // + // Возвращает nil ошибку, если игрок делает правильный ход в контексте + // предоставленной доски. В противном случае ExercisePlayer возвращает одну из + // ошибок этого пакета, чтобы указать, как и почему игрок не прошел валидацию. + func ExercisePlayer(b *chess.Board, p chess.Player) error + ``` + + Тест должен отмечать, какие инварианты нарушены и как. Ваш дизайн может + выбрать одну из двух дисциплин для сообщения о сбоях: + + * **Завершение при первой ошибке (Fail fast)**: возвращать ошибку, как + только реализация нарушает инвариант. + + Это самый простой подход, и он хорошо работает, если ожидается, что + приемочный тест будет выполняться быстро. Простые [сторожевые ошибки + (sentinels)] и [пользовательские типы] могут быть легко использованы + здесь, что, в свою очередь, облегчает тестирование самого приемочного + теста. + + ```go + for color, army := range b.Armies { + // Король никогда не должен покидать доску, потому что игра заканчивается + // матом. + if army.King == nil { + return &MissingPieceError{Color: color, Piece: chess.King} + } + } + ``` + + * **Агрегация всех сбоев (Aggregate all failures)**: собирать все сбои и + сообщать о них всех. + + Этот подход напоминает рекомендацию [продолжать выполнение (keep going)] + и может быть предпочтительнее, если ожидается, что приемочный тест будет + выполняться медленно. + + То, как вы агрегируете сбои, должно определяться тем, хотите ли вы дать + пользователям или себе возможность исследовать отдельные сбои (например, + для тестирования вашего приемочного теста). Ниже демонстрируется + использование [пользовательского типа ошибки][пользовательские типы], + который [агрегирует ошибки]: + + ```go + var badMoves []error + + move := p.Move() + if putsOwnKingIntoCheck(b, move) { + badMoves = append(badMoves, PutsSelfIntoCheckError{Move: move}) + } + + if len(badMoves) > 0 { + return SimulationError{BadMoves: badMoves} + } + return nil + ``` + +Приемочный тест должен соблюдать рекомендацию [продолжать выполнение (keep +going)], не вызывая `t.Fatal`, если тест не обнаруживает нарушение инварианта в +системе, которая тестируется. + +Например, `t.Fatal` должен быть зарезервирован для исключительных случаев, таких +как [сбой настройки](#test-helper-error-handling), как обычно: + +```go +func ExerciseGame(t *testing.T, cfg *Config, p chess.Player) error { + t.Helper() + + if cfg.Simulation == Modem { + conn, err := modempool.Allocate() + if err != nil { + t.Fatalf("No modem for the opponent could be provisioned: %v", err) + } + t.Cleanup(func() { modempool.Return(conn) }) + } + // Запустить приемочный тест (целую игру). +} +``` + +Эта техника может помочь вам создавать лаконичные, каноничные проверки. Но не +пытайтесь использовать ее, чтобы обойти [рекомендации об +утверждениях](https://neonxp.ru/pages/gostyleguide/google/decisions/#assert). + +Конечный продукт должен быть похож на этот для конечных пользователей: + +```go +// Хорошо: +package deepblue_test + +import ( + "chesstest" + "deepblue" +) + +func TestAcceptance(t *testing.T) { + player := deepblue.New() + err := chesstest.ExerciseGame(t, chesstest.SimpleGame, player) + if err != nil { + t.Errorf("Deep Blue player failed acceptance test: %v", err) + } +} +``` + +[сторожевые ошибки (sentinels)]: + https://google.github.io/styleguide/go/index.html#gotip +[пользовательские типы]: https://google.github.io/styleguide/go/index.html#gotip +[агрегирует ошибки]: https://google.github.io/styleguide/go/index.html#gotip + +<a id="use-real-transports"></a> + +### Используйте реальные транспорты (Use real transports) + +При тестировании интеграции компонентов, особенно когда HTTP или RPC +используются в качестве базового транспорта между компонентами, предпочитайте +использовать реальный базовый транспорт для подключения к тестовой версии +бэкенда. + +Например, предположим, что код, который вы хотите протестировать (иногда +называемый "системой под тестом" или SUT), взаимодействует с бэкендом, +реализующим API [долго выполняющихся операций (long running operations)]. Чтобы +протестировать ваш SUT, используйте реальный [OperationsClient], подключенный к +[тестовому двойнику (test +double)](https://abseil.io/resources/swe-book/html/ch13.html#basic_concepts) +(например, моку, заглушке или фейку) [OperationsServer]. + +[тестовому двойнику (test double)]: + https://abseil.io/resources/swe-book/html/ch13.html#basic_concepts +[долго выполняющихся операций (long running operations)]: + https://pkg.go.dev/google.golang.org/genproto/googleapis/longrunning +[OperationsClient]: + https://pkg.go.dev/google.golang.org/genproto/googleapis/longrunning#OperationsClient +[OperationsServer]: + https://pkg.go.dev/google.golang.org/genproto/googleapis/longrunning#OperationsServer + +Это рекомендуется вместо ручной реализации клиента из-за сложности правильной +имитации поведения клиента. Используя production-клиент с тестовым сервером, вы +гарантируете, что ваш тест использует как можно больше реального кода. + +**Совет:** По возможности используйте тестовую библиотеку, предоставленную +авторами тестируемого сервиса. + +<a id="t-fatal"></a> + +### `t.Error` против `t.Fatal` + +Как обсуждалось в [решениях](https://neonxp.ru/pages/gostyleguide/google/decisions/#keep-going), тесты, как правило, не +должны прерываться при первой встреченной проблеме. + +Однако некоторые ситуации требуют, чтобы тест не продолжался. Вызов `t.Fatal` +уместен, когда какая-то часть настройки теста завершается неудачей, особенно во +[вспомогательных функциях настройки теста], без которых вы не можете запустить +остальную часть теста. В табличном тесте `t.Fatal` уместен для сбоев, которые +настраивают всю тестовую функцию до начала цикла теста. Сбои, которые +затрагивают одну запись в таблице теста и делают невозможным продолжение работы +с этой записью, должны сообщаться следующим образом: + +* Если вы не используете подтесты `t.Run`, используйте `t.Error`, за которым + следует оператор `continue` для перехода к следующей записи таблицы. +* Если вы используете подтесты (и вы внутри вызова `t.Run`), используйте + `t.Fatal`, который завершает текущий подтест и позволяет вашему тестовому + случаю перейти к следующему подтесту. + +**Предупреждение:** Не всегда безопасно вызывать `t.Fatal` и подобные функции. +[Подробнее здесь](#t-fatal-goroutine). + +[вспомогательных функциях настройки теста]: #test-helper-error-handling + +<a id="test-helper-error-handling"></a> + +### Обработка ошибок во вспомогательных тестовых функциях (Error handling in test helpers) + +**Примечание:** В этом разделе обсуждаются [тестовые помощники (test helpers)] в +том смысле, в котором Go использует этот термин: функции, которые выполняют +настройку и очистку теста, а не общие средства утверждений. См. раздел [тестовые +функции](#test-functions) для более подробного обсуждения. + +[тестовые помощники (test helpers)]: decisions#mark-test-helpers + +Операции, выполняемые тестовым помощником, иногда завершаются неудачей. +Например, настройка каталога с файлами включает ввод-вывод, который может +завершиться неудачей. Когда тестовые помощники завершаются неудачей, их сбой +часто означает, что тест не может продолжиться, поскольку не выполнилось +предварительное условие настройки. Когда это происходит, предпочтительнее +вызвать одну из функций `Fatal` в помощнике: + +```go +// Хорошо: +func mustAddGameAssets(t *testing.T, dir string) { + t.Helper() + if err := os.WriteFile(path.Join(dir, "pak0.pak"), pak0, 0644); err != nil { + t.Fatalf("Setup failed: could not write pak0 asset: %v", err) + } + if err := os.WriteFile(path.Join(dir, "pak1.pak"), pak1, 0644); err != nil { + t.Fatalf("Setup failed: could not write pak1 asset: %v", err) + } +} +``` + +Это делает вызывающую сторону чище, чем если бы помощник возвращал ошибку самому +тесту: + +```go +// Плохо: +func addGameAssets(t *testing.T, dir string) error { + t.Helper() + if err := os.WriteFile(path.Join(d, "pak0.pak"), pak0, 0644); err != nil { + return err + } + if err := os.WriteFile(path.Join(d, "pak1.pak"), pak1, 0644); err != nil { + return err + } + return nil +} +``` + +**Предупреждение:** Не всегда безопасно вызывать `t.Fatal` и подобные функции. +[Подробнее](#t-fatal-goroutine) здесь. + +Сообщение об ошибке должно включать описание того, что произошло. Это важно, так +как вы можете предоставлять тестовый API многим пользователям, особенно с +увеличением количества шагов, производящих ошибки, в помощнике. Когда тест +завершается неудачей, пользователь должен знать, где и почему. + +**Совет:** Go 1.14 представила функцию [`t.Cleanup`], которую можно использовать +для регистрации функций очистки, которые запускаются при завершении вашего +теста. Функция также работает с тестовыми помощниками. См. [GoTip #4: Cleaning +Up Your Tests](https://google.github.io/styleguide/go/index.html#gotip) для +рекомендаций по упрощению тестовых помощников. + +Сниппет ниже в вымышленном файле `paint_test.go` демонстрирует, как +`(*testing.T).Helper` влияет на сообщение об ошибке в тесте Go: + +```go +package paint_test + +import ( + "fmt" + "testing" +) + +func paint(color string) error { + return fmt.Errorf("no %q paint today", color) +} + +func badSetup(t *testing.T) { + // Здесь должен быть вызов t.Helper, но его нет. + if err := paint("taupe"); err != nil { + t.Fatalf("Could not paint the house under test: %v", err) // строка 15 + } +} + +func goodSetup(t *testing.T) { + t.Helper() + if err := paint("lilac"); err != nil { + t.Fatalf("Could not paint the house under test: %v", err) + } +} + +func TestBad(t *testing.T) { + badSetup(t) + // ... +} + +func TestGood(t *testing.T) { + goodSetup(t) // строка 32 + // ... +} +``` + +Вот пример вывода при запуске. Обратите внимание на выделенный текст и на то, +как он отличается: + +```text +=== RUN TestBad + paint_test.go:15: Could not paint the house under test: no "taupe" paint today +--- FAIL: TestBad (0.00s) +=== RUN TestGood + paint_test.go:32: Could not paint the house under test: no "lilac" paint today +--- FAIL: TestGood (0.00s) +FAIL +``` + +Ошибка с `paint_test.go:15` относится к строке функции настройки, которая +завершилась неудачей в `badSetup`: + +`t.Fatalf("Could not paint the house under test: %v", err)` + +Тогда как `paint_test.go:32` относится к строке теста, которая завершилась +неудачей в `TestGood`: + +`goodSetup(t)` + +Правильное использование `(*testing.T).Helper` гораздо лучше определяет +местоположение сбоя, когда: + +* вспомогательные функции растут +* вспомогательные функции вызывают другие вспомогательные функции +* количество использований вспомогательных функций в тестовых функциях растет + +**Совет:** Если вспомогательная функция вызывает `(*testing.T).Error` или +`(*testing.T).Fatal`, предоставьте некоторый контекст в строке формата, чтобы +помочь определить, что пошло не так и почему. + +**Совет:** Если ничто из того, что делает помощник, не может привести к неудаче +теста, ему не нужно вызывать `t.Helper`. Упростите его сигнатуру, удалив `t` из +списка параметров функции. + +[`t.Cleanup`]: https://pkg.go.dev/testing#T.Cleanup + +<a id="t-fatal-goroutine"></a> + +### Не вызывайте `t.Fatal` из отдельных горутин (Don't call `t.Fatal` from separate goroutines) + +Как [документировано в пакете testing](https://pkg.go.dev/testing#T), +неправильно вызывать `t.FailNow`, `t.Fatal` и т.д. из любой горутины, кроме той, +которая запускает функцию Test (или подтест). Если ваш тест запускает новые +горутины, они не должны вызывать эти функции внутри этих горутин. + +[Тестовые помощники](#test-functions) обычно не сигнализируют о сбое из новых +горутин, поэтому для них допустимо использовать `t.Fatal`. В случае сомнений +вызовите `t.Error` и вернитесь. + +```go +// Хорошо: +func TestRevEngine(t *testing.T) { + engine, err := Start() + if err != nil { + t.Fatalf("Engine failed to start: %v", err) + } + + num := 11 + var wg sync.WaitGroup + wg.Add(num) + for i := 0; i < num; i++ { + go func() { + defer wg.Done() + if err := engine.Vroom(); err != nil { + // Здесь нельзя использовать t.Fatalf. + t.Errorf("No vroom left on engine: %v", err) + return + } + if rpm := engine.Tachometer(); rpm > 1e6 { + t.Errorf("Inconceivable engine rate: %d", rpm) + } + }() + } + wg.Wait() + + if seen := engine.NumVrooms(); seen != num { + t.Errorf("engine.NumVrooms() = %d, want %d", seen, num) + } +} +``` + +Добавление `t.Parallel` к тесту или подтесту не делает небезопасным вызов +`t.Fatal`. + +Когда все вызовы API `testing` находятся в [тестовой функции](#test-functions), +обычно легко заметить неправильное использование, потому что ключевое слово `go` +легко увидеть. Передача аргументов `testing.T` усложняет отслеживание такого +использования. Обычно причина передачи этих аргументов — введение тестового +помощника, и они не должны зависеть от тестируемой системы. Поэтому, если +тестовый помощник [регистрирует фатальную ошибку +теста](#test-helper-error-handling), он может и должен делать это из горутины +теста. + +<a id="t-field-names"></a> + +### Используйте имена полей в литералах структур (Use field names in struct literals) + +<a id="t-field-labels"></a> + +В табличных тестах предпочитайте указывать имена полей при инициализации +литералов структур тестовых случаев. Это полезно, когда тестовые случаи +охватывают большое вертикальное пространство (например, более 20-30 строк), +когда есть соседние поля с одинаковым типом, а также когда вы хотите опустить +поля, имеющие нулевое значение. Например: + +```go +// Хорошо: +func TestStrJoin(t *testing.T) { + tests := []struct { + slice []string + separator string + skipEmpty bool + want string + }{ + { + slice: []string{"a", "b", ""}, + separator: ",", + want: "a,b,", + }, + { + slice: []string{"a", "b", ""}, + separator: ",", + skipEmpty: true, + want: "a,b", + }, + // ... + } + // ... +} +``` + +<a id="t-common-setup-scope"></a> + +### Ограничивайте код настройки конкретными тестами (Keep setup code scoped to specific tests) + +По возможности настройка ресурсов и зависимостей должна быть максимально +ограничена конкретными тестовыми случаями. Например, учитывая функцию настройки: + +```go +// mustLoadDataSet загружает набор данных для тестов. +// +// Этот пример очень прост и легко читается. Часто реалистичная настройка более +// сложная, подверженная ошибкам и потенциально медленная. +func mustLoadDataset(t *testing.T) []byte { + t.Helper() + data, err := os.ReadFile("path/to/your/project/testdata/dataset") + + if err != nil { + t.Fatalf("Could not load dataset: %v", err) + } + return data +} +``` + +Вызовите `mustLoadDataset` явно в тестовых функциях, которые в этом нуждаются: + +```go +// Хорошо: +func TestParseData(t *testing.T) { + data := mustLoadDataset(t) + parsed, err := ParseData(data) + if err != nil { + t.Fatalf("Unexpected error parsing data: %v", err) + } + want := &DataTable{ /* ... */ } + if got := parsed; !cmp.Equal(got, want) { + t.Errorf("ParseData(data) = %v, want %v", got, want) + } +} + +func TestListContents(t *testing.T) { + data := mustLoadDataset(t) + contents, err := ListContents(data) + if err != nil { + t.Fatalf("Unexpected error listing contents: %v", err) + } + want := []string{ /* ... */ } + if got := contents; !cmp.Equal(got, want) { + t.Errorf("ListContents(data) = %v, want %v", got, want) + } +} + +func TestRegression682831(t *testing.T) { + if got, want := guessOS("zpc79.example.com"), "grhat"; got != want { + t.Errorf(`guessOS("zpc79.example.com") = %q, want %q`, got, want) + } +} +``` + +Тестовая функция `TestRegression682831` не использует набор данных и поэтому не +вызывает `mustLoadDataset`, которая может быть медленной и подверженной сбоям: + +```go +// Плохо: +var dataset []byte + +func TestParseData(t *testing.T) { + // Как описано выше без вызова mustLoadDataset напрямую. +} + +func TestListContents(t *testing.T) { + // Как описано выше без вызова mustLoadDataset напрямую. +} + +func TestRegression682831(t *testing.T) { + if got, want := guessOS("zpc79.example.com"), "grhat"; got != want { + t.Errorf(`guessOS("zpc79.example.com") = %q, want %q`, got, want) + } +} + +func init() { + dataset = mustLoadDataset() +} +``` + +Пользователь может захотеть запустить функцию изолированно от других и не должен +быть наказан этими факторами: + +```shell +# Нет причин для выполнения дорогой инициализации. +$ go test -run TestRegression682831 +``` + +<a id="t-custom-main"></a> + +#### Когда использовать пользовательскую точку входа `TestMain` (When to use a custom `TestMain` entrypoint) + +Если **все тесты в пакете** требуют общей настройки и **настройка требует +очистки (teardown)**, вы можете использовать [пользовательскую точку входа +testmain]. Это может произойти, если ресурс, требующийся тестовым случаям, +особенно дорог в настройке, и стоимость должна быть амортизирована. Обычно к +этому моменту вы уже убрали несвязанные тесты из набора тестов. Обычно это +используется только для [функциональных тестов (functional tests)]. + +Использование пользовательского `TestMain` **не должно быть вашим первым +выбором** из-за количества осторожности, которое требуется для правильного +использования. Сначала рассмотрите, достаточно ли решения в разделе +[*амортизация общей настройки теста*] или обычного [тестового помощника] для +ваших нужд. + +[пользовательскую точку входа testmain]: + https://golang.org/pkg/testing/#hdr-Main +[функциональных тестов (functional tests)]: + https://en.wikipedia.org/wiki/Functional_testing +[*амортизация общей настройки теста*]: #t-setup-amortization +[тестового помощника]: #t-common-setup-scope + +```go +// Хорошо: +var db *sql.DB + +func TestInsert(t *testing.T) { /* omitted */ } + +func TestSelect(t *testing.T) { /* omitted */ } + +func TestUpdate(t *testing.T) { /* omitted */ } + +func TestDelete(t *testing.T) { /* omitted */ } + +// runMain устанавливает зависимости теста и в конечном итоге выполняет тесты. +// Она определена как отдельная функция, чтобы этапы настройки могли четко +// откладывать (defer) свои шаги очистки. +func runMain(ctx context.Context, m *testing.M) (code int, err error) { + ctx, cancel := context.WithCancel(ctx) + defer cancel() + + d, err := setupDatabase(ctx) + if err != nil { + return 0, err + } + defer d.Close() // Явно очищаем базу данных. + db = d // db определена как переменная на уровне пакета. + + // m.Run() выполняет обычные, определенные пользователем тестовые функции. + // Любые операторы defer, которые были сделаны, будут выполнены после завершения m.Run(). + return m.Run(), nil +} + +func TestMain(m *testing.M) { + code, err := runMain(context.Background(), m) + if err != nil { + // Сообщения о сбоях должны записываться в STDERR, что и использует log.Fatal. + log.Fatal(err) + } + // ПРИМЕЧАНИЕ: операторы defer не выполняются после здесь из-за os.Exit + // завершающего процесс. + os.Exit(code) +} +``` + +В идеале тестовый случай является герметичным (hermetic) между вызовами самого +себя и между другими тестовыми случаями. + +По крайней мере, убедитесь, что отдельные тестовые случаи сбрасывают любое +глобальное состояние, которое они изменили, если они это сделали (например, если +тесты работают с внешней базой данных). + +<a id="t-setup-amortization"></a> + +#### Амортизация общей настройки теста (Amortizing common test setup) + +Использование `sync.Once` может быть уместным, хотя и не обязательно, если все +из следующего верно для общей настройки: + +* Она дорогая. +* Она применяется только к некоторым тестам. +* Она не требует очистки. + +```go +// Хорошо: +var dataset struct { + once sync.Once + data []byte + err error +} + +func mustLoadDataset(t *testing.T) []byte { + t.Helper() + dataset.once.Do(func() { + data, err := os.ReadFile("path/to/your/project/testdata/dataset") + // dataset определена как переменная на уровне пакета. + dataset.data = data + dataset.err = err + }) + if err := dataset.err; err != nil { + t.Fatalf("Could not load dataset: %v", err) + } + return dataset.data +} +``` + +Когда `mustLoadDataset` используется в нескольких тестовых функциях, ее +стоимость амортизируется: + +```go +// Хорошо: +func TestParseData(t *testing.T) { + data := mustLoadDataset(t) + + // Как описано выше. +} + +func TestListContents(t *testing.T) { + data := mustLoadDataset(t) + + // Как описано выше. +} + +func TestRegression682831(t *testing.T) { + if got, want := guessOS("zpc79.example.com"), "grhat"; got != want { + t.Errorf(`guessOS("zpc79.example.com") = %q, want %q`, got, want) + } +} +``` + +Причина, по которой общая очистка сложна, заключается в том, что нет единого +места для регистрации процедур очистки. Если функция настройки (в данном случае +`mustLoadDataset`) полагается на контекст, `sync.Once` может быть +проблематичным. Это потому, что второй из двух конкурентных вызовов функции +настройки должен будет ждать завершения первого вызова, прежде чем вернуться. +Этот период ожидания нельзя легко заставить уважать отмену контекста. + +<a id="string-concat"></a> + +## Конкатенация строк (String concatenation) + +Есть несколько способов конкатенации строк в Go. Некоторые примеры включают: + +* Оператор "+" +* `fmt.Sprintf` +* `strings.Builder` +* `text/template` +* `safehtml/template` + +Хотя не существует универсального правила, какой выбрать, следующие рекомендации +описывают, когда каждый метод предпочтителен. + +<a id="string-concat-simple"></a> + +### Предпочитайте "+" для простых случаев (Prefer "+" for simple cases) + +Предпочитайте использовать "+" при конкатенации нескольких строк. Этот метод +синтаксически самый простой и не требует импорта. + +```go +// Хорошо: +key := "projectid: " + p +``` + +<a id="string-concat-fmt"></a> + +### Предпочитайте `fmt.Sprintf` при форматировании (Prefer `fmt.Sprintf` when formatting) + +Предпочитайте использовать `fmt.Sprintf` при построении сложной строки с +форматированием. Использование многих операторов "+" может затмить конечный +результат. + +```go +// Хорошо: +str := fmt.Sprintf("%s [%s:%d]-> %s", src, qos, mtu, dst) +``` + +```go +// Плохо: +bad := src.String() + " [" + qos.String() + ":" + strconv.Itoa(mtu) + "]-> " + dst.String() +``` + +**Лучшая практика:** Когда результатом операции построения строки является +`io.Writer`, не конструируйте временную строку с помощью `fmt.Sprintf`, чтобы +просто отправить ее в Writer. Вместо этого используйте `fmt.Fprintf`, чтобы +отправлять прямо в Writer. + +Когда форматирование еще сложнее, предпочитайте [`text/template`] или +[`safehtml/template`] по мере необходимости. + +[`text/template`]: https://pkg.go.dev/text/template +[`safehtml/template`]: https://pkg.go.dev/github.com/google/safehtml/template + +<a id="string-concat-piecemeal"></a> + +### Предпочитайте `strings.Builder` для построения строки по частям (Prefer `strings.Builder` for constructing a string piecemeal) + +Предпочитайте использовать `strings.Builder` при построении строки по частям. +`strings.Builder` занимает амортизированное линейное время, тогда как "+" и +`fmt.Sprintf` занимают квадратичное время при последовательном вызове для +формирования большей строки. + +```go +// Хорошо: +b := new(strings.Builder) +for i, d := range digitsOfPi { + fmt.Fprintf(b, "the %d digit of pi is: %d\n", i, d) +} +str := b.String() +``` + +**Примечание:** Для более подробного обсуждения см. [GoTip #29: Building +Strings Efficiently](https://google.github.io/styleguide/go/index.html#gotip). + +<a id="string-constants"></a> + +### Константные строки (Constant strings) + +Предпочитайте использовать обратные кавычки (\`) при создании константных, +многострочных строковых литералов. + +```go +// Хорошо: +usage := `Usage: + +custom_tool [args]` +``` + +```go +// Плохо: +usage := "" + + "Usage:\n" + + "\n" + + "custom_tool [args]" +``` + +<a id="globals"></a> + +## Глобальное состояние (Global state) + +Библиотеки не должны заставлять своих клиентов использовать API, которые +полагаются на [глобальное состояние (global +state)](https://en.wikipedia.org/wiki/Global_variable). Им рекомендуется не +раскрывать API или экспортировать переменные на [уровне пакета (package level)], +которые контролируют поведение для всех клиентов как часть их API. В остальной +части раздела "глобальное" и "состояние на уровне пакета" используются как +синонимы. + +Вместо этого, если ваша функциональность поддерживает состояние, позвольте вашим +клиентам создавать и использовать экземпляры значений. + +**Важно:** Хотя это руководство применимо ко всем разработчикам, оно наиболее +критично для поставщиков инфраструктуры, которые предлагают библиотеки, +интеграции и сервисы другим командам. + +[глобальное состояние (global state)]: + https://en.wikipedia.org/wiki/Global_variable +[уровне пакета (package level)]: https://go.dev/ref/spec#TopLevelDecl + +```go +// Хорошо: +// Пакет sidecar управляет подпроцессами, которые предоставляют функции для приложений. +package sidecar + +type Registry struct { plugins map[string]*Plugin } + +func New() *Registry { return &Registry{plugins: make(map[string]*Plugin)} } + +func (r *Registry) Register(name string, p *Plugin) error { ... } +``` + +Ваши пользователи будут создавать необходимые им данные (`*sidecar.Registry`), а +затем передавать их как явную зависимость: + +```go +// Хорошо: +package main + +func main() { + sidecars := sidecar.New() + if err := sidecars.Register("Cloud Logger", cloudlogger.New()); err != nil { + log.Exitf("Could not setup cloud logger: %v", err) + } + cfg := &myapp.Config{Sidecars: sidecars} + myapp.Run(context.Background(), cfg) +} +``` + +Существуют разные подходы к миграции существующего кода для поддержки передачи +зависимостей. Основной, который вы будете использовать, — передача зависимостей +в качестве параметров конструкторам, функциям, методам или полям структур в +цепочке вызовов. + +См. также: + +* [Go Tip #5: Slimming Your Client + Libraries](https://google.github.io/styleguide/go/index.html#gotip) +* [Go Tip #24: Use Case-Specific + Constructions](https://google.github.io/styleguide/go/index.html#gotip) +* [Go Tip #40: Improving Time Testability with Function + Parameters](https://google.github.io/styleguide/go/index.html#gotip) +* [Go Tip #41: Identify Function Call + Parameters](https://google.github.io/styleguide/go/index.html#gotip) +* [Go Tip #44: Improving Time Testability with Struct + Fields](https://google.github.io/styleguide/go/index.html#gotip) +* [Go Tip #80: Dependency Injection + Principles](https://google.github.io/styleguide/go/index.html#gotip) + +API, которые не поддерживают явную передачу зависимостей, становятся хрупкими с +увеличением числа клиентов: + +```go +// Плохо: +package sidecar + +var registry = make(map[string]*Plugin) + +func Register(name string, p *Plugin) error { /* регистрирует плагин в registry */ } +``` + +Рассмотрим, что происходит в случае тестов, проверяющих код, который транзитивно +зависит от sidecar для облачного логирования. + +```go +// Плохо: +package app + +import ( + "cloudlogger" + "sidecar" + "testing" +) + +func TestEndToEnd(t *testing.T) { + // Система под тестом (SUT) полагается на sidecar для production облачного + // логгера, который уже зарегистрирован. + ... // Проверяем SUT и проверяем инварианты. +} + +func TestRegression_NetworkUnavailability(t *testing.T) { + // У нас был сбой из-за сетевого раздела, который сделал облачный логгер + // неработоспособным, поэтому мы добавили регрессионный тест для проверки SUT с + // тестовым двойником, имитирующим недоступность сети для логгера. + sidecar.Register("cloudlogger", cloudloggertest.UnavailableLogger) + ... // Проверяем SUT и проверяем инварианты. +} + +func TestRegression_InvalidUser(t *testing.T) { + // Система под тестом (SUT) полагается на sidecar для production облачного + // логгера, который уже зарегистрирован. + // + // Упс. cloudloggertest.UnavailableLogger все еще зарегистрирован с + // предыдущего теста. + ... // Проверяем SUT и проверяем инварианты. +} +``` + +Тесты Go выполняются последовательно по умолчанию, поэтому вышеуказанные тесты +выполняются как: + +1. `TestEndToEnd` +2. `TestRegression_NetworkUnavailability`, который переопределяет значение по + умолчанию cloudlogger +3. `TestRegression_InvalidUser`, который требует значения по умолчанию + cloudlogger, зарегистрированного в `package sidecar` + +Это создает тестовый случай, зависящий от порядка, что нарушает запуск с +фильтрами тестов и не позволяет тестам запускаться параллельно или +шардироваться. + +Использование глобального состояния создает проблемы, на которые нет простых +ответов для вас и клиентов API: + +* Что произойдет, если клиенту нужно использовать разные и отдельно работающие + наборы `Plugin` (например, для поддержки нескольких серверов) в одном + процессе? + +* Что произойдет, если клиент захочет заменить зарегистрированный `Plugin` + альтернативной реализацией в тесте, например, [тестовым двойником]? + + Что произойдет, если тестам клиента требуется герметичность между + экземплярами `Plugin` или между всеми зарегистрированными плагинами? + +* Что произойдет, если несколько клиентов `Register` плагин `Plugin` под одним + и тем же именем? Кто победит, если вообще победит? + + Как следует [обрабатывать](https://neonxp.ru/pages/gostyleguide/google/decisions/#handle-errors) ошибки? Если код + вызывает panic или `log.Fatal`, будет ли это всегда [уместно для всех мест, + в которых может быть вызван API](https://neonxp.ru/pages/gostyleguide/google/decisions/#dont-panic)? Может ли клиент + проверить, что он не делает ничего плохого, прежде чем сделать это? + +* Существуют ли определенные этапы начальной загрузки программы или ее + жизненного цикла, во время которых можно вызывать `Register`, а когда нет? + + Что произойдет, если `Register` будет вызван в неподходящее время? Клиент + может вызвать `Register` в [`func + init`](https://go.dev/ref/spec#Package_initialization), до разбора флагов + или после `main`. Этап, на котором вызывается функция, влияет на обработку + ошибок. Если автор API предполагает, что API вызывается *только* во время + инициализации программы без требования, чтобы это было так, это + предположение может подтолкнуть автора к проектированию обработки ошибок для + [завершения программы](https://neonxp.ru/pages/gostyleguide/google/best-practices/#program-init), моделируя API как + функцию типа `Must`. Завершение не подходит для библиотечных функций общего + назначения, которые могут использоваться на любом этапе. + +* Что, если потребности в параллелизме клиента и дизайнера не совпадают? + +См. также: + +* [Go Tip #36: Enclosing Package-Level + State](https://google.github.io/styleguide/go/index.html#gotip) +* [Go Tip #71: Reducing Parallel Test + Flakiness](https://google.github.io/styleguide/go/index.html#gotip) +* [Go Tip #80: Dependency Injection + Principles](https://google.github.io/styleguide/go/index.html#gotip) +* Обработка ошибок: [Look Before You + Leap](https://docs.python.org/3/glossary.html#term-LBYL) против [Easier to + Ask for Forgiveness than + Permission](https://docs.python.org/3/glossary.html#term-EAFP) +* [Unit Testing Practices on Public APIs] + +Глобальное состояние имеет каскадные эффекты на [здоровье кодовой базы +Google](https://neonxp.ru/pages/gostyleguide/google/guide/.md#maintainability). К глобальному состоянию следует подходить с +**крайней тщательностью**. + +[Глобальное состояние бывает нескольких форм](#globals-forms), и вы можете +использовать несколько [лакмусовых тестов, чтобы определить, когда оно +безопасно](#globals-litmus-tests). + +[Unit Testing Practices on Public APIs]: index.md#unit-testing-practices + +<a id="globals-forms"></a> + +### Основные формы API состояния пакета (Major forms of package state APIs) + +Ниже перечислены несколько наиболее распространенных проблемных форм API: + +* Переменные верхнего уровня, независимо от того, экспортируются они или нет. + + ```go + // Плохо: + package logger + + // Sinks управляет выходными источниками по умолчанию для API логирования этого пакета. + // Эта переменная должна быть установлена во время инициализации пакета и никогда после этого. + var Sinks []Sink + ``` + + См. [лакмусовые тесты](#globals-litmus-tests), чтобы узнать, когда они + безопасны. + +* Шаблон [локатора служб (service locator + pattern)](https://en.wikipedia.org/wiki/Service_locator_pattern). См. + [первый пример](#globals). Сам шаблон локатора служб не является + проблематичным, а проблема в том, что локатор определен как глобальный. + +* Реестры для [обратных вызовов + (callbacks)](https://en.wikipedia.org/wiki/Callback_\(computer_programming\)) + и подобного поведения. + + ```go + // Плохо: + package health + + var unhealthyFuncs []func + + func OnUnhealthy(f func()) { + unhealthyFuncs = append(unhealthyFuncs, f) + } + ``` + +* "Толстые" (thick) клиентские синглтоны для таких вещей, как бэкенды, + хранилища, уровни доступа к данным и другие системные ресурсы. Они часто + создают дополнительные проблемы с надежностью служб. + + ```go + // Плохо: + package useradmin + + var client pb.UserAdminServiceClientInterface + + func Client() *pb.UserAdminServiceClient { + if client == nil { + client = ... // Настройка клиента. + } + return client + } + ``` + +> **Примечание:** Многие устаревшие API в кодовой базе Google не следуют этому +> руководству; фактически, некоторые стандартные библиотеки Go позволяют +> настраивать поведение через глобальные значения. Тем не менее, нарушение +> этого руководства устаревшим API **[не должно использоваться как +> прецедент](https://neonxp.ru/pages/gostyleguide/google/guide/#local-consistency)** для продолжения шаблона. +> +> Лучше инвестировать в правильный дизайн API сегодня, чем платить за его +> перепроектирование позже. + +<a id="globals-litmus-tests"></a> + +### Лакмусовые тесты (Litmus tests) + +[API, использующие шаблоны выше](#globals-forms), небезопасны, когда: + +* Несколько функций взаимодействуют через глобальное состояние при выполнении + в одной программе, несмотря на то, что в остальном они независимы (например, + написаны разными авторами в совершенно разных каталогах). +* Независимые тестовые случаи взаимодействуют друг с другом через глобальное + состояние. +* Пользователи API склонны заменять или подменять глобальное состояние для + целей тестирования, особенно чтобы заменить любую часть состояния [тестовым + двойником], например, заглушкой, фейком, шпионом или моком. +* Пользователи должны учитывать особые требования к порядку при взаимодействии + с глобальным состоянием: `func init`, разобраны ли уже флаги и т.д. + +При условии, что вышеуказанные условия избегаются, существует **несколько +ограниченных обстоятельств, при которых эти API безопасны**, а именно, когда +верно любое из следующего: + +* Глобальное состояние логически постоянно + ([пример](https://github.com/klauspost/compress/blob/290f4cfacb3eff892555a491e3eeb569a48665e7/zstd/snappy.go#L413)). +* Наблюдаемое поведение пакета является бессостоятельным (stateless). + Например, общедоступная функция может использовать частную глобальную + переменную в качестве кэша, но пока вызывающая сторона не может отличить + попадания в кэш от промахов, функция является бессостоятельной. +* Глобальное состояние не просачивается в вещи, внешние по отношению к + программе, такие как sidecar-процессы или файлы в общей файловой системе. +* Нет ожидания предсказуемого поведения + ([пример](https://pkg.go.dev/math/rand)). + +> **Примечание:** +> [Sidecar-процессы](https://www.oreilly.com/library/view/designing-distributed-systems/9781491983638/ch02.html) +> могут **не** быть строго локальными для процесса. Они могут и часто +> используются совместно более чем одним процессом приложения. Более того, эти +> sidecar часто взаимодействуют с внешними распределенными системами. +> +> Кроме того, те же правила бессостоятельности, идемпотентности и локальности в +> дополнение к базовым соображениям выше применялись бы к коду самого +> sidecar-процесса! + +Пример одной из таких безопасных ситуаций — [`package +image`](https://pkg.go.dev/image) с его функцией +[`image.RegisterFormat`](https://pkg.go.dev/image#RegisterFormat). Рассмотрим +лакмусовые тесты, примененные к типичному декодеру, например, для обработки +формата [PNG](https://pkg.go.dev/image/png): + +* Множественные вызовы API `package image`, использующие зарегистрированные + декодеры (например, `image.Decode`), не могут мешать друг другу, аналогично + и для тестов. Единственное исключение — `image.RegisterFormat`, но это + смягчается пунктами ниже. +* Крайне маловероятно, что пользователь захочет заменить декодер [тестовым + двойником], так как декодер PNG является примером случая, когда предпочтение + нашей кодовой базы реальным объектам применяется. Однако пользователь с + большей вероятностью заменит декодер тестовым двойником, если декодер + состоятельно взаимодействует с ресурсами операционной системы (например, + сетью). +* Коллизии при регистрации возможны, хотя на практике они, вероятно, редки. +* Декодеры являются бессостоятельными, идемпотентными и чистыми (pure). + +<a id="globals-default-instance"></a> + +### Предоставление экземпляра по умолчанию (Providing a default instance) + +Хотя и не рекомендуется, допустимо предоставить упрощенный API, использующий +состояние на уровне пакета, если вам нужно максимизировать удобство для +пользователя. + +Следуйте [лакмусовым тестам](#globals-litmus-tests) с этими рекомендациями в +таких случаях: + +1. Пакет должен предлагать клиентам возможность создавать изолированные + экземпляры типов пакета, как [описано выше](#globals-forms). +2. Общедоступные API, использующие глобальное состояние, должны быть тонкой + прослойкой (thin proxy) к предыдущему API. Хороший пример этого — + [`http.Handle`](https://pkg.go.dev/net/http#Handle), внутренне вызывающий + [`(*http.ServeMux).Handle`](https://pkg.go.dev/net/http#ServeMux.Handle) на + переменной пакета + [`http.DefaultServeMux`](https://pkg.go.dev/net/http#DefaultServeMux). +3. Этот API уровня пакета должен использоваться только [целями сборки + бинарников (binary build targets)], а не [библиотеками (libraries)], если + только библиотеки не предпринимают рефакторинг для поддержки передачи + зависимостей. Инфраструктурные библиотеки, которые могут быть импортированы + другими пакетами, не должны полагаться на состояние на уровне пакета + импортируемых ими пакетов. + + Например, поставщик инфраструктуры, реализующий sidecar, который должен + использоваться совместно с другими командами, использующими API сверху, + должен предложить API для этого: + + ```go + // Хорошо: + package cloudlogger + + func New() *Logger { ... } + + func Register(r *sidecar.Registry, l *Logger) { + r.Register("Cloud Logging", l) + } + ``` + +4. Этот API уровня пакета должен [документировать](#documentation-conventions) + и обеспечивать соблюдение своих инвариантов (например, на каком этапе + жизненного цикла программы его можно вызывать, можно ли использовать его + параллельно). Кроме того, он должен предоставлять API для сброса глобального + состояния к известному хорошему значению по умолчанию (например, для + облегчения тестирования). + +[целями сборки бинарников (binary build targets)]: + https://github.com/bazelbuild/rules_go/blob/master/docs/go/core/rules.md#go_binary +[библиотеками (libraries)]: + https://github.com/bazelbuild/rules_go/blob/master/docs/go/core/rules.md#go_library + +См. также: + +* [Go Tip #36: Enclosing Package-Level + State](https://google.github.io/styleguide/go/index.html#gotip) +* [Go Tip #80: Dependency Injection + Principles](https://google.github.io/styleguide/go/index.html#gotip) diff --git a/content/pages/gostyleguide/google/decisions.md b/content/pages/gostyleguide/google/decisions.md new file mode 100644 index 0000000..acb17b7 --- /dev/null +++ b/content/pages/gostyleguide/google/decisions.md @@ -0,0 +1,4057 @@ +--- +order: 2 +title: Google Go Style Guide — Решения +--- + +# Решения по стилю Go + +Оригинал: https://google.github.io/styleguide/go/decisions + +[Обзор](https://neonxp.ru/pages/gostyleguide/google/) | [Руководство](https://neonxp.ru/pages/gostyleguide/google/guide) | [Решения](https://neonxp.ru/pages/gostyleguide/google/decisions) | +[Лучшие практики](https://neonxp.ru/pages/gostyleguide/google/best-practices) + + +**Примечание:** Это часть серии документов, описывающих [Стиль Go](https://neonxp.ru/pages/gostyleguide/google/) в +Google. Этот документ является **[нормативным](https://neonxp.ru/pages/gostyleguide/google/#normative), но не +[каноническим](https://neonxp.ru/pages/gostyleguide/google/#canonical)** и подчиняется [основному руководству по +стилю](https://neonxp.ru/pages/gostyleguide/google/guide/). Подробнее см. [в обзоре](https://neonxp.ru/pages/gostyleguide/google/#about). + +<a id="about"></a> + +## Об этом документе + +В этом документе содержатся решения по стилю, призванные унифицировать и дать +стандартные рекомендации, пояснения и примеры для советов, которые дают +наставники по читаемости Go. + +Этот документ **не является исчерпывающим** и будет пополняться со временем. В +случаях, когда [основное руководство по стилю](https://neonxp.ru/pages/gostyleguide/google/guide/) противоречит приведенным +здесь рекомендациям, **руководство по стилю имеет приоритет**, и этот документ +должен быть обновлен соответственно. + +Полный набор документов по стилю Go см. в +[Обзоре](https://google.github.io/styleguide/go#about). + +Следующие разделы были перемещены из "Решений по стилю" в другие части +руководства: + +* **MixedCaps**: см. [guide#mixed-caps](https://neonxp.ru/pages/gostyleguide/google/guide/#mixed-caps) <a + id="mixed-caps"></a> + +* **Форматирование**: см. [guide#formatting](https://neonxp.ru/pages/gostyleguide/google/guide/#formatting) <a + id="formatting"></a> + +* **Длина строки**: см. [guide#line-length](https://neonxp.ru/pages/gostyleguide/google/guide/#line-length) <a + id="line-length"></a> + +<a id="naming"></a> + +## Именование + +Общие рекомендации по именованию см. в разделе об именовании в [основном +руководстве по стилю](https://neonxp.ru/pages/gostyleguide/google/guide/#naming). Следующие разделы дают дальнейшие +разъяснения по конкретным областям именования. + +<a id="underscores"></a> + +### Подчеркивания + +Имена в Go, как правило, не должны содержать подчеркиваний. Существует три +исключения из этого принципа: + +1. Имена пакетов, которые импортируются только сгенерированным кодом, могут + содержать подчеркивания. Подробнее о том, как выбирать имена многословных + пакетов, см. в разделе [имена пакетов](#package-names). +1. Имена тестовых (`Test`), бенчмарк (`Benchmark`) и примеров (`Example`) + функций в файлах `*_test.go` могут содержать подчеркивания. +1. Низкоуровневые библиотеки, взаимодействующие с операционной системой или + cgo, могут повторно использовать идентификаторы, как это сделано в + [`syscall`]. Ожидается, что это будет очень редко встречаться в большинстве + кодовых баз. + +**Примечание:** Имена файлов исходного кода не являются идентификаторами Go и не +должны следовать этим соглашениям. Они могут содержать подчеркивания. + +[`syscall`]: https://pkg.go.dev/syscall#pkg-constants + +<a id="package-names"></a> + +### Имена пакетов + +<a id="TOC-PackageNames"></a> + +В Go имена пакетов должны быть краткими и использовать только строчные буквы и +цифры (например, [`k8s`], [`oauth2`]). Многословные имена пакетов должны +оставаться целыми и в нижнем регистре (например, [`tabwriter`] вместо +`tabWriter`, `TabWriter` или `tab_writer`). + +Избегайте выбора имен пакетов, которые могут быть [затенены] часто используемыми +локальными именами переменных. Например, `usercount` — лучшее имя пакета, чем +`count`, так как `count` — часто используемое имя переменной. + +Имена пакетов Go не должны содержать подчеркиваний. Если вам нужно импортировать +пакет, который содержит их в своем имени (обычно из сгенерированного или +стороннего кода), его необходимо переименовать при импорте в имя, подходящее для +использования в коде Go. + +Исключением является то, что имена пакетов, которые импортируются только +сгенерированным кодом, могут содержать подчеркивания. Конкретные примеры +включают: + +* Использование суффикса `_test` для модульных тестов, проверяющих только + экспортированный API пакета (пакет `testing` называет это ["черным + ящиком"](https://pkg.go.dev/testing)). Например, пакет `linkedlist` должен + определять свои модульные тесты "черного ящика" в пакете с именем + `linkedlist_test` (не `linked_list_test`) + +* Использование подчеркиваний и суффикса `_test` для пакетов, содержащих + функциональные или интеграционные тесты. Например, интеграционный тест + сервиса связного списка может называться `linked_list_service_test` + +* Использование суффикса `_test` для [примеров документации на уровне + пакета](https://go.dev/blog/examples) + +[`tabwriter`]: https://pkg.go.dev/text/tabwriter +[`k8s`]: https://pkg.go.dev/k8s.io/client-go/kubernetes +[`oauth2`]: https://pkg.go.dev/golang.org/x/oauth2 +[shadowed]: best-practices#shadowing + +Избегайте неинформативных имен пакетов, таких как `util`, `utility`, `common`, +`helper`, `model`, `testhelper` и т.д., которые могут побуждать пользователей +пакета [переименовывать его при импорте](#import-renaming). См.: + +* [Рекомендации по так называемым "служебным + пакетам"](https://neonxp.ru/pages/gostyleguide/google/best-practices/#util-packages) +* [Go Tip #97: Что в + имени](https://google.github.io/styleguide/go/index.html#gotip) +* [Go Tip #108: Сила хорошего имени + пакета](https://google.github.io/styleguide/go/index.html#gotip) + +Когда импортированный пакет переименовывается (например, `import foopb +"path/to/foo_go_proto"`), локальное имя пакета должно соответствовать правилам +выше, так как локальное имя определяет, как на символы в пакете ссылаются в +файле. Если данный импорт переименован в нескольких файлах, особенно в одном и +том же или соседних пакетах, по возможности следует использовать одно и то же +локальное имя для согласованности. + +<!--#include file="/go/g3doc/style/includes/special-name-exception.md"--> + +См. также: [Пост в блоге Go об именах +пакетов](https://go.dev/blog/package-names). + +<a id="receiver-names"></a> + +### Имена получателей (Receiver) + +<a id="TOC-ReceiverNames"></a> + +Имена [получателей] (receiver) должны быть: + +* Краткими (обычно одна или две буквы) +* Сокращениями для самого типа +* Применяться последовательно для каждого получателя этого типа + +Длинное имя | Лучшее имя +----------------------------- | ------------------------- +`func (tray Tray)` | `func (t Tray)` +`func (info *ResearchInfo)` | `func (ri *ResearchInfo)` +`func (this *ReportWriter)` | `func (w *ReportWriter)` +`func (self *Scanner)` | `func (s *Scanner)` + +[получателей]: https://golang.org/ref/spec#Method_declarations + +<a id="constant-names"></a> + +### Имена констант + +Имена констант должны использовать [MixedCaps], как и все остальные имена в Go. +([Экспортируемые] константы начинаются с заглавной буквы, а неэкспортируемые — +со строчной.) Это применимо, даже если это нарушает соглашения в других языках. +Имена констант не должны быть производными от их значений и должны объяснять, +что означает это значение. + +```go +// Хорошо: +const MaxPacketSize = 512 + +const ( + ExecuteBit = 1 << iota + WriteBit + ReadBit +) +``` + +[MixedCaps]: guide#mixed-caps +[Экспортируемые]: https://tour.golang.org/basics/3 + +Не используйте имена констант не в стиле MixedCaps или константы с префиксом +`K`. + +```go +// Плохо: +const MAX_PACKET_SIZE = 512 +const kMaxBufferSize = 1024 +const KMaxUsersPergroup = 500 +``` + +Называйте константы в соответствии с их ролью, а не значениями. Если у константы +нет роли, кроме ее значения, то нет необходимости определять ее как константу. + +```go +// Плохо: +const Twelve = 12 + +const ( + UserNameColumn = "username" + GroupColumn = "group" +) +``` + +<!--#include file="/go/g3doc/style/includes/special-name-exception.md"--> + +<a id="initialisms"></a> + +### Аббревиатуры и акронимы (Initialisms) + +<a id="TOC-Initialisms"></a> + +Слова в именах, которые являются аббревиатурами или акронимами (например, `URL` +и `NATO`), должны иметь одинаковый регистр. `URL` должен появляться как `URL` +или `url` (как в `urlPony` или `URLPony`), но никогда как `Url`. Как общее +правило, идентификаторы (например, `ID` и `DB`) также должны быть написаны с +заглавной буквы, аналогично их использованию в английской прозе. + +* В именах с несколькими аббревиатурами (например, `XMLAPI`, потому что оно + содержит `XML` и `API`) каждая буква в данной аббревиатуре должна иметь один + регистр, но каждая аббревиатура в имени не обязана иметь одинаковый регистр. +* В именах с аббревиатурой, содержащей строчную букву (например, `DDoS`, + `iOS`, `gRPC`), аббревиатура должна отображаться, как в стандартной прозе, + если только вам не нужно изменить первую букву ради [экспортируемости + (exportedness)]. В этих случаях вся аббревиатура должна быть в одном + регистре (например, `ddos`, `IOS`, `GRPC`). + +[экспортируемости (exportedness)]: + https://golang.org/ref/spec#Exported_identifiers + +<!-- Keep this table narrow. If it must grow wider, replace with a list. --> + +Использование в английском | Область видимости | Правильно | Неправильно +-------------------------- | ----------------- | --------- | -------------------------------------- +XML API | Экспортировано | `XMLAPI` | `XmlApi`, `XMLApi`, `XmlAPI`, `XMLapi` +XML API | Не экспортировано | `xmlAPI` | `xmlapi`, `xmlApi` +iOS | Экспортировано | `IOS` | `Ios`, `IoS` +iOS | Не экспортировано | `iOS` | `ios` +gRPC | Экспортировано | `GRPC` | `Grpc` +gRPC | Не экспортировано | `gRPC` | `grpc` +DDoS | Экспортировано | `DDoS` | `DDOS`, `Ddos` +DDoS | Не экспортировано | `ddos` | `dDoS`, `dDOS` +ID | Экспортировано | `ID` | `Id` +ID | Не экспортировано | `id` | `iD` +DB | Экспортировано | `DB` | `Db` +DB | Не экспортировано | `db` | `dB` +Txn | Экспортировано | `Txn` | `TXN` + +<!--#include file="/go/g3doc/style/includes/special-name-exception.md"--> + +<a id="getters"></a> + +### Геттеры (Getters) + +<a id="TOC-Getters"></a> + +Имена функций и методов не должны использовать префикс `Get` или `get`, если +только базовое понятие не использует слово "get" (например, HTTP GET). +Предпочитайте начинать имя с существительного напрямую, например, используйте +`Counts` вместо `GetCounts`. + +Если функция включает выполнение сложных вычислений или удаленного вызова, +вместо `Get` можно использовать другое слово, например `Compute` или `Fetch`, +чтобы читателю было ясно, что вызов функции может занять время и может +блокироваться или завершиться неудачей. + +<!--#include file="/go/g3doc/style/includes/special-name-exception.md"--> + +<a id="variable-names"></a> + +### Имена переменных + +<a id="TOC-VariableNames"></a> + +Общее эмпирическое правило заключается в том, что длина имени должна быть +пропорциональна размеру его области видимости и обратно пропорциональна +количеству раз, которое оно используется в этой области. Переменная, созданная +на уровне файла, может потребовать несколько слов, тогда как переменная в +области видимости одного внутреннего блока может быть одним словом или даже +всего одним-двумя символами, чтобы сохранить код понятным и избежать лишней +информации. + +Вот приблизительный базовый уровень. Эти численные рекомендации не являются +строгими правилами. Применяйте суждение, основанное на контексте, [ясности] и +[лаконичности]. + +* Малая область видимости — это область, в которой выполняется одна или две + небольшие операции, скажем, 1-7 строк. +* Средняя область видимости — это несколько небольших или одна большая + операция, скажем, 8-15 строк. +* Большая область видимости — это одна или несколько больших операций, скажем, + 15-25 строк. +* Очень большая область видимости — это все, что занимает больше страницы + (скажем, более 25 строк). + +[ясности]: guide#clarity +[лаконичности]: guide#concision + +Имя, которое может быть совершенно понятным (например, `c` для счетчика) в +маленькой области видимости, может оказаться недостаточным в большей области и +потребует уточнения, чтобы напомнить читателю о его назначении дальше по коду. +Область видимости, в которой много переменных или переменных, представляющих +похожие значения или понятия, может потребовать более длинных имен переменных, +чем предполагает область видимости. + +Специфичность понятия также может помочь сохранить имя переменной кратким. +Например, если используется только одна база данных, короткое имя переменной +вроде `db`, которое обычно зарезервировано для очень малых областей видимости, +может оставаться совершенно понятным даже при очень большой области видимости. В +этом случае одно слово `database`, вероятно, приемлемо в зависимости от размера +области видимости, но не обязательно, поскольку `db` — очень распространенное +сокращение для этого слова с малым количеством альтернативных интерпретаций. + +Имя локальной переменной должно отражать то, что она содержит, и как она +используется в текущем контексте, а не откуда взялось значение. Например, часто +бывает, что лучшее локальное имя переменной не совпадает с именем поля структуры +или поля protobuf. + +В общем: + +* Однобуквенные имена, такие как `count` или `options`, — хорошая отправная + точка. +* Дополнительные слова могут быть добавлены для различения похожих имен, + например `userCount` и `projectCount`. +* Не просто выбрасывайте буквы, чтобы сэкономить на печати. Например, + `Sandbox` предпочтительнее, чем `Sbx`, особенно для экспортируемых имен. +* Опускайте [типы и слова, похожие на типы] из большинства имен переменных. + * Для числа `userCount` — лучшее имя, чем `numUsers` или `usersInt`. + * Для среза `users` — лучшее имя, чем `userSlice`. + * Допустимо включать квалификатор, похожий на тип, если в области + видимости есть две версии значения, например, у вас может быть ввод, + сохраненный в `ageString`, и `age` для распарсенного значения. +* Опускайте слова, которые ясны из [окружающего контекста]. Например, в + реализации метода `UserCount` локальная переменная с именем `userCount`, + вероятно, избыточна; `count`, `users` или даже `c` так же читаемы. + +[типы и слова, похожие на типы]: #repetitive-with-type +[окружающего контекста]: #repetitive-in-context + +<a id="v"></a> + +#### Однобуквенные имена переменных + +Однобуквенные имена переменных могут быть полезным инструментом для минимизации +[повторов](#repetition), но также могут сделать код излишне непрозрачным. +Ограничьте их использование случаями, когда полное слово очевидно и где было бы +излишне повторять его вместо однобуквенной переменной. + +В общем: + +* Для [переменной-получателя метода] предпочтительно одно- или двухбуквенное + имя. +* Использование знакомых имен переменных для распространенных типов часто + полезно: + * `r` для `io.Reader` или `*http.Request` + * `w` для `io.Writer` или `http.ResponseWriter` +* Однобуквенные идентификаторы допустимы в качестве целочисленных переменных + цикла, особенно для индексов (например, `i`) и координат (например, `x` и + `y`). +* Сокращения могут быть допустимыми идентификаторами цикла, если область + видимости короткая, например `for _, n := range nodes { ... }`. + +[переменной-получателя метода]: #receiver-names + +<a id="repetition"></a> + +### Повторы + +<!-- +Примечание для будущих редакторов: + +Не используйте термин "stutter" (заикание) для обозначения случаев, когда имя повторяется. +--> + +Исходный код Go должен избегать ненужных повторов. Один из распространенных +источников этого — повторяющиеся имена, которые часто включают ненужные слова +или повторяют свой контекст или тип. Сам код также может быть излишне +повторяющимся, если один и тот же или похожий сегмент кода появляется несколько +раз в непосредственной близости. + +Повторяющееся именование может принимать многие формы, включая: + +<a id="repetitive-with-package"></a> + +#### Имя пакета vs. экспортируемый символ + +При именовании экспортируемых символов имя пакета всегда видно за пределами +вашего пакета, поэтому избыточную информацию между ними следует сократить или +устранить. Если пакет экспортирует только один тип, и он назван в честь самого +пакета, каноническое имя для конструктора — `New`, если он требуется. + +> **Примеры:** Повторяющееся имя -> Лучшее имя +> +> * `widget.NewWidget` -> `widget.New` +> * `widget.NewWidgetWithName` -> `widget.NewWithName` +> * `db.LoadFromDatabase` -> `db.Load` +> * `goatteleportutil.CountGoatsTeleported` -> `gtutil.CountGoatsTeleported` +> или `goatteleport.Count` +> * `myteampb.MyTeamMethodRequest` -> `mtpb.MyTeamMethodRequest` или +> `myteampb.MethodRequest` + +<a id="repetitive-with-type"></a> + +#### Имя переменной vs. тип + +Компилятор всегда знает тип переменной, и в большинстве случаев читателю также +понятен тип переменной по тому, как она используется. Уточнять тип переменной +необходимо только если ее значение появляется дважды в одной и той же области +видимости. + +Повторяющееся имя | Лучшее имя +------------------------------- | ---------------------- +`var numUsers int` | `var users int` +`var nameString string` | `var name string` +`var primaryProject *Project` | `var primary *Project` + +Если значение появляется в нескольких формах, это можно уточнить либо с помощью +дополнительного слова, например `raw` и `parsed`, либо с помощью базового +представления: + +```go +// Хорошо: +limitRaw := r.FormValue("limit") +limit, err := strconv.Atoi(limitRaw) +``` + +```go +// Хорошо: +limitStr := r.FormValue("limit") +limit, err := strconv.Atoi(limitStr) +``` + +<a id="repetitive-in-context"></a> + +#### Внешний контекст vs. локальные имена + +Имена, включающие информацию из окружающего их контекста, часто создают лишний +шум без пользы. Имя пакета, имя метода, имя типа, имя функции, путь импорта и +даже имя файла могут предоставить контекст, который автоматически квалифицирует +все имена внутри. + +```go +// Плохо: +// В пакете "ads/targeting/revenue/reporting" +type AdsTargetingRevenueReport struct{} + +func (p *Project) ProjectName() string +``` + +```go +// Хорошо: +// В пакете "ads/targeting/revenue/reporting" +type Report struct{} + +func (p *Project) Name() string +``` + +```go +// Плохо: +// В пакете "sqldb" +type DBConnection struct{} +``` + +```go +// Хорошо: +// В пакете "sqldb" +type Connection struct{} +``` + +```go +// Плохо: +// В пакете "ads/targeting" +func Process(in *pb.FooProto) *Report { + adsTargetingID := in.GetAdsTargetingID() +} +``` + +```go +// Хорошо: +// В пакете "ads/targeting" +func Process(in *pb.FooProto) *Report { + id := in.GetAdsTargetingID() +} +``` + +Повторение, как правило, следует оценивать в контексте использования символа, а +не изолированно. Например, следующий код содержит множество имен, которые могут +быть хороши в некоторых обстоятельствах, но избыточны в контексте: + +```go +// Плохо: +func (db *DB) UserCount() (userCount int, err error) { + var userCountInt64 int64 + if dbLoadError := db.LoadFromDatabase("count(distinct users)", &userCountInt64); dbLoadError != nil { + return 0, fmt.Errorf("failed to load user count: %s", dbLoadError) + } + userCount = int(userCountInt64) + return userCount, nil +} +``` + +Вместо этого информацию об именах, которые ясны из контекста или использования, +часто можно опустить: + +```go +// Хорошо: +func (db *DB) UserCount() (int, error) { + var count int64 + if err := db.Load("count(distinct users)", &count); err != nil { + return 0, fmt.Errorf("failed to load user count: %s", err) + } + return int(count), nil +} +``` + +<a id="commentary"></a> + +## Комментарии + +Соглашения, касающиеся комментариев (что комментировать, какой стиль +использовать, как предоставлять исполняемые примеры и т.д.), предназначены для +поддержки удобства чтения документации публичного API. Подробнее см. [Effective +Go](http://golang.org/doc/effective_go.html#commentary). + +Раздел о [соглашениях по документации] в документе о лучших практиках +рассматривает это подробнее. + +**Лучшая практика:** Используйте [предпросмотр документации (doc preview)] во +время разработки и проверки кода, чтобы увидеть, является ли документация и +исполняемые примеры полезными и представлены ли они так, как вы ожидаете. + +**Совет:** Godoc использует очень мало специального форматирования; списки и +фрагменты кода обычно должны иметь отступ, чтобы избежать переноса строк. Кроме +отступа, декорации, как правило, следует избегать. + +[предпросмотр документации (doc preview)]: best-practices#documentation-preview +[соглашениям по документации]: best-practices#documentation-conventions + +<a id="comment-line-length"></a> + +### Длина строк комментария + +Убедитесь, что комментарии читаемы из исходного кода даже на узких экранах. + +Когда комментарий становится слишком длинным, рекомендуется разбить его на +несколько однострочных комментариев. По возможности стремитесь к комментариям, +которые будут хорошо читаться на терминале шириной 80 колонок, однако это не +жесткий предел; в Go нет фиксированного ограничения длины строки для +комментариев. Стандартная библиотека, например, часто предпочитает разрывать +комментарий по пунктуации, что иногда оставляет отдельные строки ближе к отметке +60-70 символов. + +Существует множество существующего кода, в котором комментарии превышают 80 +символов в длину. Эти рекомендации не следует использовать как оправдание для +изменения такого кода в ходе проверки на читаемость (см. +[согласованность](https://neonxp.ru/pages/gostyleguide/google/guide/#consistency)), хотя командам рекомендуется использовать +возможность обновлять комментарии в соответствии с этим руководством в рамках +других рефакторингов. Основная цель этого руководства — гарантировать, что все +наставники по читаемости Go дают одинаковые рекомендации, когда и если +рекомендации даются. + +Подробнее о комментариях см. в [этом посте из блога Go о документации]. + +[этом посте из блога Go о документации]: + https://blog.golang.org/godoc-documenting-go-code + +```text +# Хорошо: +// Это абзац комментария. +// Длина отдельных строк не имеет значения в Godoc; +// но выбор переноса делает его легко читаемым на узких экранах. +// +// Не беспокойтесь слишком о длинном URL: +// https://supercalifragilisticexpialidocious.example.com:8080/Animalia/Chordata/Mammalia/Rodentia/Geomyoidea/Geomyidae/ +// +// Аналогично, если у вас есть другая информация, которая становится неудобной +// из-за слишком большого количества разрывов строк, используйте свое суждение и включите длинную строку, +// если она помогает, а не мешает. +``` + +Избегайте комментариев, которые будут многократно переноситься на маленьких +экранах, что ухудшает удобство чтения. + +```text +# Плохо: +// Это абзац комментария. Длина отдельных строк не имеет значения в Godoc; +// но выбор переноса создает неровные строки на узких экранах или при просмотре кода, +// что может раздражать, особенно в блоке комментариев, который будет переноситься +// многократно. +// +// Не беспокойтесь слишком о длинном URL: +// https://supercalifragilisticexpialidocious.example.com:8080/Animalia/Chordata/Mammalia/Rodentia/Geomyoidea/Geomyidae/ +``` + +<a id="doc-comments"></a> + +### Документирующие комментарии (Doc comments) + +<a id="TOC-DocComments"></a> + +Все экспортируемые имена верхнего уровня должны иметь документирующие +комментарии, как и неэкспортируемые объявления типов или функций с неочевидным +поведением или смыслом. Эти комментарии должны быть [полными предложениями], +которые начинаются с имени описываемого объекта. Артикль ("a", "an", "the") +может предшествовать имени, чтобы оно читалось более естественно. + +```go +// Хорошо: +// Request представляет запрос на выполнение команды. +type Request struct { ... + +// Encode записывает JSON-кодировку req в w. +func Encode(w io.Writer, req *Request) { ... +``` + +Документирующие комментарии появляются в [Godoc](https://pkg.go.dev/) и +выводятся в IDE, поэтому их следует писать для всех, кто использует пакет. + +[полными предложениями]: #comment-sentences + +Документирующий комментарий относится к следующему символу или группе полей, +если он появляется в структуре. + +```go +// Хорошо: +// Options настраивает сервис управления группами. +type Options struct { + // Общая настройка: + Name string + Group *FooGroup + + // Зависимости: + DB *sql.DB + + // Кастомизация: + LargeGroupThreshold int // опционально; по умолчанию: 10 + MinimumMembers int // опционально; по умолчанию: 2 +} +``` + +**Лучшая практика:** Если у вас есть документирующие комментарии для +неэкспортируемого кода, следуйте тому же обычаю, как если бы он был +экспортируемым (а именно, начиная комментарий с неэкспортируемого имени). Это +упрощает его экспорт позже простой заменой неэкспортируемого имени на новое +экспортируемое в комментариях и коде. + +<a id="comment-sentences"></a> + +### Предложения в комментариях + +<a id="TOC-CommentSentences"></a> + +Комментарии, которые являются полными предложениями, должны начинаться с +заглавной буквы и заканчиваться пунктуацией, как стандартные английские +предложения. (В качестве исключения можно начать предложение с +некапитализированного имени идентификатора, если оно иначе понятно. Такие +случаи, вероятно, лучше делать только в начале абзаца.) + +Комментарии, которые являются фрагментами предложений, не имеют таких требований +к пунктуации или капитализации. + +[Документирующие комментарии] всегда должны быть полными предложениями, и +поэтому всегда должны начинаться с заглавной буквы и заканчиваться пунктуацией. +Простые комментарии в конце строки (особенно для полей структуры) могут быть +простыми фразами, которые предполагают, что имя поля является подлежащим. + +```go +// Хорошо: +// Server обрабатывает подачу цитат из собрания сочинений Шекспира. +type Server struct { + // BaseDir указывает на базовый каталог, в котором хранятся работы Шекспира. + // + // Ожидается следующая структура каталога: + // {BaseDir}/manifest.json + // {BaseDir}/{name}/{name}-part{number}.txt + BaseDir string + + WelcomeMessage string // отображается при входе пользователя + ProtocolVersion string // проверяется для входящих запросов + PageLength int // строк на странице при печати (опционально; по умолчанию: 20) +} +``` + +[Документирующие комментарии]: #doc-comments + +<a id="examples"></a> + +### Примеры + +<a id="TOC-Examples"></a> + +Пакеты должны четко документировать предполагаемое использование. Постарайтесь +предоставить [исполняемый пример]; примеры появляются в Godoc. Исполняемые +примеры принадлежат тестовому файлу, а не файлу исходного кода продакшена. +Смотрите этот пример ([Godoc], [исходный код]). + +[исполняемый пример]: http://blog.golang.org/examples +[Godoc]: https://pkg.go.dev/time#example-Duration +[исходный код]: + https://cs.opensource.google/go/go/+/HEAD:src/time/example_test.go + +Если предоставить исполняемый пример нецелесообразно, пример кода может быть +предоставлен внутри комментариев к коду. Как и другие фрагменты кода и командной +строки в комментариях, он должен следовать стандартным соглашениям +форматирования. + +<a id="named-result-parameters"></a> + +### Именованные возвращаемые параметры + +<a id="TOC-NamedResultParameters"></a> + +При именовании параметров учитывайте, как сигнатуры функций отображаются в +Godoc. Имя самой функции и тип возвращаемых параметров часто достаточно ясны. + +```go +// Хорошо: +func (n *Node) Parent1() *Node +func (n *Node) Parent2() (*Node, error) +``` + +Если функция возвращает два или более параметра одного типа, добавление имен +может быть полезным. + +```go +// Хорошо: +func (n *Node) Children() (left, right *Node, err error) +``` + +Если вызывающая сторона должна выполнить действие над определенными +возвращаемыми параметрами, их именование может помочь подсказать, какое это +действие: + +```go +// Хорошо: +// WithTimeout возвращает контекст, который будет отменен не позднее, чем через длительность d +// от текущего момента. +// +// Вызывающая сторона должна обеспечить вызов возвращенной функции cancel, когда +// контекст больше не нужен, чтобы предотвратить утечку ресурсов. +func WithTimeout(parent Context, d time.Duration) (ctx Context, cancel func()) +``` + +В приведенном выше коде отмена — это конкретное действие, которое должна +выполнить вызывающая сторона. Однако, если бы возвращаемые параметры были +записаны просто как `(Context, func())`, было бы неясно, что подразумевается под +"функцией отмены". + +Не используйте именованные возвращаемые параметры, когда имена создают [ненужные +повторы](#repetitive-with-type). + +```go +// Плохо: +func (n *Node) Parent1() (node *Node) +func (n *Node) Parent2() (node *Node, err error) +``` + +Не называйте возвращаемые параметры, чтобы избежать объявления переменной внутри +функции. Эта практика приводит к излишней многословности API в обмен на +незначительную краткость реализации. + +[Голые возвраты (Naked returns)] допустимы только в маленькой функции. Как +только это функция среднего размера, будьте явны со своими возвращаемыми +значениями. Аналогично, не называйте возвращаемые параметры только потому, что +это позволяет вам использовать голые возвраты. [Ясность](https://neonxp.ru/pages/gostyleguide/google/guide/#clarity) всегда +важнее, чем сэкономить несколько строк в вашей функции. + +Всегда приемлемо назвать возвращаемый параметр, если его значение должно быть +изменено в отложенном замыкании. + +> **Совет:** Типы часто могут быть понятнее, чем имена в сигнатурах функций. +> [GoTip #38: Функции как именованные типы] демонстрирует это. +> +> В [`WithTimeout`] выше, реальный код использует [`CancelFunc`] вместо простого +> `func()` в списке возвращаемых параметров и требует небольших усилий для +> документирования. + +[Голые возвраты (Naked returns)]: https://tour.golang.org/basics/7 +[GoTip #38: Функции как именованные типы]: + https://google.github.io/styleguide/go/index.html#gotip +[`WithTimeout`]: https://pkg.go.dev/context#WithTimeout +[`CancelFunc`]: https://pkg.go.dev/context#CancelFunc + +<a id="package-comments"></a> + +### Комментарии к пакетам + +<a id="TOC-PackageComments"></a> + +Комментарии к пакету должны появляться непосредственно перед объявлением пакета, +без пустой строки между комментарием и именем пакета. Пример: + +```go +// Хорошо: +// Package math предоставляет базовые константы и математические функции. +// +// Этот пакет не гарантирует битовой идентичности результатов на разных архитектурах. +package math +``` + +Должен быть ровно один комментарий к пакету на пакет. Если пакет состоит из +нескольких файлов, ровно в одном из файлов должен быть комментарий к пакету. + +Комментарии для пакетов `main` имеют немного другую форму, где имя правила +`go_binary` в BUILD-файле заменяет имя пакета. + +```go +// Хорошо: +// Команда seed_generator — это утилита, которая генерирует файл сида Finch +// из набора JSON-конфигураций исследований. +package main +``` + +Другие стили комментариев допустимы, если имя бинарника точно такое же, как +написано в BUILD-файле. Когда имя бинарника — первое слово, его заглавная буква +обязательна, даже если оно не совпадает с написанием вызова в командной строке. + +```go +// Хорошо: +// Binary seed_generator ... +// Command seed_generator ... +// Program seed_generator ... +// The seed_generator command ... +// The seed_generator program ... +// Seed_generator ... +``` + +Советы: + +* Примеры вызовов командной строки и использования API могут быть полезной + документацией. Для форматирования Godoc сделайте отступ для строк + комментария, содержащих код. + +* Если нет очевидного основного файла или если комментарий к пакету необычайно + длинный, допустимо поместить документирующий комментарий в файл с именем + `doc.go`, содержащий только комментарий и объявление пакета. + +* Многострочные комментарии могут использоваться вместо нескольких + однострочных. Это в первую очередь полезно, если документация содержит + разделы, которые могут быть полезны для копирования и вставки из исходного + файла, как, например, примеры командной строки (для бинарников) и примеры + шаблонов. + + ```go + // Хорошо: + /* + Команда seed_generator — это утилита, которая генерирует файл сида Finch + из набора JSON-конфигураций исследований. + + seed_generator *.json | base64 > finch-seed.base64 + */ + package template + ``` + +* Комментарии, предназначенные для сопровождающих и относящиеся ко всему + файлу, обычно размещаются после объявлений импорта. Они не отображаются в + Godoc и не подчиняются приведенным выше правилам для комментариев к пакетам. + +<a id="imports"></a> + +## Импорты + +<a id="TOC-Imports"></a> + +<a id="import-renaming"></a> + +### Переименование импортов + +Импорты пакетов обычно не должны переименовываться, но есть случаи, когда они +должны быть переименованы или когда переименование улучшает читаемость. + +Локальные имена для импортированных пакетов должны следовать [рекомендациям по +именованию пакетов](#package-names), включая запрет на использование +подчеркиваний и заглавных букв. Старайтесь быть +[последовательными](https://neonxp.ru/pages/gostyleguide/google/guide/#consistency), всегда используя одно и то же локальное +имя для одного и того же импортированного пакета. + +Импортированный пакет *должен* быть переименован, чтобы избежать конфликта имен +с другими импортами. (Следствие из этого: [хорошие имена +пакетов](#package-names) не должны требовать переименования.) В случае конфликта +имен предпочтительнее переименовать наиболее локальный или специфичный для +проекта импорт. + +Сгенерированные пакеты протоколов буфера *должны* быть переименованы, чтобы +удалить подчеркивания из их имен, и их локальные имена должны иметь суффикс +`pb`. Подробнее см. [лучшие практики для proto и заглушек +(stubs)](https://neonxp.ru/pages/gostyleguide/google/best-practices/#import-protos). + +```go +// Хорошо: +import ( + foosvcpb "path/to/package/foo_service_go_proto" +) +``` + +Наконец, импортированный, несгенерированный пакет *может* быть переименован, +если он имеет неинформативное имя (например, `util` или `v1`) Делайте это +экономно: не переименовывайте пакет, если код, окружающий использование пакета, +передает достаточно контекста. По возможности предпочитайте рефакторинг самого +пакета с более подходящим именем. + +```go +// Хорошо: +import ( + core "github.com/kubernetes/api/core/v1" + meta "github.com/kubernetes/apimachinery/pkg/apis/meta/v1beta1" +) +``` + +Если вам нужно импортировать пакет, имя которого конфликтует с распространенным +локальным именем переменной, которое вы хотите использовать (например, `url`, +`ssh`), и вы хотите переименовать пакет, предпочтительный способ сделать это — +использовать суффикс `pkg` (например, `urlpkg`). Обратите внимание, что +возможно затенение пакета локальной переменной; это переименование необходимо +только если пакет все еще нужно использовать, когда такая переменная находится в +области видимости. + +<a id="import-grouping"></a> + +### Группировка импортов + +Импорты должны быть организованы в следующие группы по порядку: + +1. Пакеты стандартной библиотеки + +1. Другие пакеты (проекта и вендорные) + +1. Импорты Protocol Buffer (например, `fpb "path/to/foo_go_proto"`) + +1. Импорт для [побочных эффектов (side + effects)](https://go.dev/doc/effective_go#blank_import) (например, `_ + "path/to/package"`) + +```go +// Хорошо: +package main + +import ( + "fmt" + "hash/adler32" + "os" + + "github.com/dsnet/compress/flate" + "golang.org/x/text/encoding" + "google.golang.org/protobuf/proto" + + foopb "myproj/foo/proto/proto" + + _ "myproj/rpc/protocols/dial" + _ "myproj/security/auth/authhooks" +) +``` + +<a id="import-blank"></a> + +### "Пустой" импорт (`import _`) + +<a id="TOC-ImportBlank"></a> + +Пакеты, которые импортируются только для их побочных эффектов (используя +синтаксис `import _ "package"`), могут импортироваться только в главном пакете +(`main`) или в тестах, которые требуют их. + +Некоторые примеры таких пакетов: + +* [time/tzdata](https://pkg.go.dev/time/tzdata) + +* [image/jpeg](https://pkg.go.dev/image/jpeg) в коде обработки изображений + +Избегайте пустых импортов в библиотечных пакетах, даже если библиотека косвенно +зависит от них. Ограничение импортов с побочными эффектами главным пакетом +помогает контролировать зависимости и позволяет писать тесты, которые полагаются +на другой импорт без конфликта или лишних затрат на сборку. + +Следующие исключения являются единственными для этого правила: + +* Вы можете использовать пустой импорт, чтобы обойти проверку на запрещенные + импорты в [статическом анализаторе nogo]. + +* Вы можете использовать пустой импорт пакета + [embed](https://pkg.go.dev/embed) в исходном файле, который использует + директиву компилятора `//go:embed`. + +**Совет:** Если вы создаете библиотечный пакет, который косвенно зависит от +импорта с побочным эффектом в продакшене, задокументируйте предполагаемое +использование. + +[статическом анализаторе nogo]: + https://github.com/bazelbuild/rules_go/blob/master/go/nogo.rst + +<a id="import-dot"></a> + +### "Точечный" импорт (`import .`) + +<a id="TOC-ImportDot"></a> + +Форма `import .` — это языковая возможность, позволяющая переносить +идентификаторы, экспортированные из другого пакета, в текущий пакет без +квалификации. Подробнее см. [спецификацию +языка](https://go.dev/ref/spec#Import_declarations). + +Не **используйте** эту возможность в кодовой базе Google; это затрудняет +понимание, откуда взялась функциональность. + +```go +// Плохо: +package foo_test + +import ( + "bar/testutil" // также импортирует "foo" + . "foo" +) + +var myThing = Bar() // Bar определен в пакете foo; квалификация не нужна. +``` + +```go +// Хорошо: +package foo_test + +import ( + "bar/testutil" // также импортирует "foo" + "foo" +) + +var myThing = foo.Bar() +``` + +<a id="errors"></a> + +## Ошибки + +<a id="returning-errors"></a> + +### Возврат ошибок + +<a id="TOC-ReturningErrors"></a> + +Используйте `error` для сигнализации о том, что функция может завершиться +неудачей. По соглашению, `error` — последний параметр результата. + +```go +// Хорошо: +func Good() error { /* ... */ } +``` + +Возврат `nil` в качестве ошибки — идиоматический способ сигнализировать об +успешной операции, которая в противном случае могла бы завершиться неудачей. +Если функция возвращает ошибку, вызывающие стороны должны рассматривать все +не-ошибочные возвращаемые значения как неопределенные, если явно не +задокументировано иначе. Обычно не-ошибочные возвращаемые значения являются их +нулевыми значениями, но на это нельзя полагаться. + +```go +// Хорошо: +func GoodLookup() (*Result, error) { + // ... + if err != nil { + return nil, err + } + return res, nil +} +``` + +Экспортируемые функции, возвращающие ошибки, должны возвращать их, используя тип +`error`. Конкретные типы ошибок подвержены тонким ошибкам: конкретный `nil` +указатель может быть завернут в интерфейс и таким образом стать ненулевым +значением (см. [FAQ по Go на эту тему][nil error]). + +```go +// Плохо: +func Bad() *os.PathError { /*...*/ } +``` + +**Совет:** Функция, принимающая аргумент [`context.Context`], обычно должна +возвращать `error`, чтобы вызывающая сторона могла определить, была ли отменена +контекст во время выполнения функции. + +[nil error]: https://golang.org/doc/faq#nil_error + +<a id="error-strings"></a> + +### Строки ошибок + +<a id="TOC-ErrorStrings"></a> + +Строки ошибок не должны начинаться с заглавной буквы (если только не начинаются +с экспортируемого имени, имени собственного или аббревиатуры) и не должны +заканчиваться пунктуацией. Это потому что строки ошибок обычно появляются внутри +другого контекста перед выводом пользователю. + +```go +// Плохо: +err := fmt.Errorf("Something bad happened.") +``` + +```go +// Хорошо: +err := fmt.Errorf("something bad happened") +``` + +С другой стороны, стиль для полного отображаемого сообщения (логирование, +неудача теста, ответ API или другой UI) зависит от ситуации, но обычно должен +быть написан с заглавной буквы. + +```go +// Хорошо: +log.Infof("Operation aborted: %v", err) +log.Errorf("Operation aborted: %v", err) +t.Errorf("Op(%q) failed unexpectedly; err=%v", args, err) +``` + +<a id="handle-errors"></a> + +### Обработка ошибок + +<a id="TOC-HandleErrors"></a> + +Код, который сталкивается с ошибкой, должен принять осознанное решение о том, +как ее обработать. Обычно нецелесообразно отбрасывать ошибки, используя +переменные `_`. Если функция возвращает ошибку, сделайте одно из следующих +действий: + +* Обработайте и исправьте ошибку немедленно. +* Верните ошибку вызывающей стороне. +* В исключительных ситуациях вызовите [`log.Fatal`] или (если абсолютно + необходимо) `panic`. + +**Примечание:** `log.Fatalf` здесь не из стандартной библиотеки log. См. +[#logging]. + +В редких обстоятельствах, когда уместно игнорировать или отбросить ошибку +(например, вызов [`(*bytes.Buffer).Write`], который, как задокументировано, +никогда не завершается неудачей), сопровождающий комментарий должен объяснять, +почему это безопасно. + +```go +// Хорошо: +var b *bytes.Buffer + +n, _ := b.Write(p) // никогда не возвращает ненулевую ошибку +``` + +Для дальнейшего обсуждения и примеров обработки ошибок см. [Effective +Go](http://golang.org/doc/effective_go.html#errors) и [лучшие +практики](https://neonxp.ru/pages/gostyleguide/google/best-practices/.md#error-handling). + +[`(*bytes.Buffer).Write`]: https://pkg.go.dev/bytes#Buffer.Write + +<a id="in-band-errors"></a> + +### Ошибки "в потоке" (In-band errors) + +<a id="TOC-In-Band-Errors"></a> + +В C и подобных языках распространено, что функции возвращают значения, такие как +-1, null или пустую строку, чтобы сигнализировать об ошибках или отсутствующих +результатах. Это известно как обработка ошибок "в потоке". + +```go +// Плохо: +// Lookup возвращает значение для ключа или -1, если нет соответствия для ключа. +func Lookup(key string) int +``` + +Неспособность проверить значение ошибки "в потоке" может привести к ошибкам и +может приписать ошибки не той функции. + +```go +// Плохо: +// Следующая строка возвращает ошибку, что Parse завершился неудачей для входного значения, +// тогда как на самом деле неудача в том, что нет соответствия для missingKey. +return Parse(Lookup(missingKey)) +``` + +Поддержка Go нескольких возвращаемых значений предоставляет лучшее решение (см. +[раздел Effective Go о множественных возвращаемых значениях]). Вместо того +чтобы требовать от клиентов проверять значение ошибки "в потоке", функция должна +возвращать дополнительное значение, чтобы указать, являются ли ее другие +возвращаемые значения валидными. Это возвращаемое значение может быть ошибкой +или булевым значением, когда объяснение не нужно, и должно быть последним +возвращаемым значением. + +```go +// Хорошо: +// Lookup возвращает значение для ключа или ok=false, если нет соответствия для ключа. +func Lookup(key string) (value string, ok bool) +``` + +Такой API предотвращает ошибочное написание вызывающей стороной +`Parse(Lookup(key))`, что вызывает ошибку времени компиляции, поскольку +`Lookup(key)` имеет 2 вывода. + +Возврат ошибок таким образом способствует более надежной и явной обработке +ошибок: + +```go +// Хорошо: +value, ok := Lookup(key) +if !ok { + return fmt.Errorf("no value for %q", key) +} +return Parse(value) +``` + +Некоторые функции стандартной библиотеки, например в пакете `strings`, +возвращают значения ошибок "в потоке". Это значительно упрощает код для +манипуляций со строками за счет необходимости большей внимательности от +программиста. В целом, код Go в кодовой базе Google должен возвращать +дополнительные значения для ошибок. + +[раздел Effective Go о множественных возвращаемых значениях]: + http://golang.org/doc/effective_go.html#multiple-returns + +<a id="indent-error-flow"></a> + +### Отступы для потока ошибок + +<a id="TOC-IndentErrorFlow"></a> + +Обрабатывайте ошибки перед продолжением выполнения остального кода. Это улучшает +читаемость кода, позволяя читателю быстро найти нормальный путь выполнения. Эта +же логика применяется к любому блоку, который проверяет условие, а затем +завершается терминальным условием (например, `return`, `panic`, `log.Fatal`). + +Код, который выполняется, если терминальное условие не выполнено, должен +появляться после блока `if` и не должен быть вложен в предложение `else`. + +```go +// Хорошо: +if err != nil { + // обработка ошибки + return // или continue, и т.д. +} +// нормальный код +``` + +```go +// Плохо: +if err != nil { + // обработка ошибки +} else { + // нормальный код, который выглядит ненормальным из-за отступа +} +``` + +> **Совет:** Если вы используете переменную более чем для нескольких строк кода, +> как правило, не стоит использовать стиль `if` с инициализатором. В этих +> случаях обычно лучше вынести объявление наружу и использовать стандартный `if` +> оператор: +> +> ```go +> // Хорошо: +> x, err := f() +> if err != nil { +> // обработка ошибки +> return +> } +> // много кода, который использует x +> // на нескольких строках +> ``` +> +> ```go +> // Плохо: +> if x, err := f(); err != nil { +> // обработка ошибки +> return +> } else { +> // много кода, который использует x +> // на нескольких строках +> } +> ``` + +Подробнее см. [Go Tip #1: Линия видимости (Line of Sight)] и [TotT: Reduce Code +Complexity by Reducing +Nesting](https://testing.googleblog.com/2017/06/code-health-reduce-nesting-reduce.html). + +[Go Tip #1: Линия видимости (Line of Sight)]: + https://google.github.io/styleguide/go/index.html#gotip + +<a id="language"></a> + +## Язык + +<a id="literal-formatting"></a> + +### Форматирование литералов + +Go обладает исключительно мощным [синтаксисом составных литералов], с помощью +которого можно выражать глубоко вложенные, сложные значения одним выражением. +По возможности следует использовать этот синтаксис литералов вместо построения +значений поле за полем. Форматирование `gofmt` для литералов, как правило, +довольно хорошее, но существуют некоторые дополнительные правила для сохранения +читаемости и поддерживаемости этих литералов. + +[синтаксисом составных литералов]: + https://golang.org/ref/spec#Composite_literals + +<a id="literal-field-names"></a> + +#### Имена полей + +Литералы структур должны указывать **имена полей** для типов, определенных вне +текущего пакета. + +* Включайте имена полей для типов из других пакетов. + + ```go + // Хорошо: + // https://pkg.go.dev/encoding/csv#Reader + r := csv.Reader{ + Comma: ',', + Comment: '#', + FieldsPerRecord: 4, + } + ``` + + Положение полей в структуре и полный набор полей (оба из которых необходимо + указать правильно, когда имена полей опущены) обычно не считаются частью + публичного API структуры; указание имени поля необходимо, чтобы избежать + ненужной связи. + + ```go + // Плохо: + r := csv.Reader{',', '#', 4, false, false, false, false} + ``` + +* Для локальных типов пакета имена полей не обязательны. + + ```go + // Хорошо: + okay := Type{42} + also := internalType{4, 2} + ``` + + Имена полей все же следует использовать, если это делает код яснее, и это + очень распространено. Например, структуру с большим количеством полей почти + всегда следует инициализировать с указанием имен полей. + + <!-- TODO: Maybe a better example here that doesn't have many fields. --> + + ```go + // Хорошо: + okay := StructWithLotsOfFields{ + field1: 1, + field2: "two", + field3: 3.14, + field4: true, + } + ``` + +<a id="literal-matching-braces"></a> + +#### Совпадение скобок + +Закрывающая часть пары фигурных скобок всегда должна появляться на строке с +таким же количеством отступов, как и открывающая скобка. Однострочные литералы +обязательно имеют это свойство. Когда литерал занимает несколько строк, +сохранение этого свойства сохраняет соответствие скобок для литералов таким же, +как соответствие скобок для обычных синтаксических конструкций Go, таких как +функции и операторы `if`. + +Самая распространенная ошибка в этой области — ставить закрывающую скобку на той +же строке, что и значение в многострочном литерале структуры. В этих случаях +строка должна заканчиваться запятой, а закрывающая скобка должна появляться на +следующей строке. + +```go +// Хорошо: +good := []*Type\{\{Key: "value"\}\} +``` + +```go +// Хорошо: +good := []*Type{ + {Key: "multi"}, + {Key: "line"}, +} +``` + +```go +// Плохо: +bad := []*Type{ + {Key: "multi"}, + {Key: "line"}} +``` + +```go +// Плохо: +bad := []*Type{ + { + Key: "value"}, +} +``` + +<a id="literal-cuddled-braces"></a> + +#### "Объединенные" скобки (Cuddled braces) + +Удаление пробела между фигурными скобками (так называемое "объединение" их) для +литералов срезов и массивов допустимо только когда оба следующих условия +истинны. + +* [Отступы совпадают](#literal-matching-braces) +* Внутренние значения также являются литералами или сборщиками protobuf (то + есть не переменной или другим выражением) + +```go +// Хорошо: +good := []*Type{ + { // Не объединены + Field: "value", + }, + { + Field: "value", + }, +} +``` + +```go +// Хорошо: +good := []*Type{\{ // Правильно объединены + Field: "value", +}, { + Field: "value", +}\} +``` + +```go +// Хорошо: +good := []*Type{ + first, // Не могут быть объединены + {Field: "second"}, +} +``` + +```go +// Хорошо: +okay := []*pb.Type{pb.Type_builder{ + Field: "first", // Сборщики Proto могут быть объединены для экономии вертикального пространства +}.Build(), pb.Type_builder{ + Field: "second", +}.Build()} +``` + +```go +// Плохо: +bad := []*Type{ + first, + { + Field: "second", + }\} +``` + +<a id="literal-repeated-type-names"></a> + +#### Повторяющиеся имена типов + +Повторяющиеся имена типов могут быть опущены в литералах срезов и карт (map). +Это может помочь уменьшить загромождение. Приемлемый случай для явного +повторения имен типов — это работа со сложным типом, который не является +распространенным в вашем проекте, когда повторяющиеся имена типов находятся на +строках, далеко отстоящих друг от друга, и могут напоминать читателю о +контексте. + +```go +// Хорошо: +good := []*Type{ + {A: 42}, + {A: 43}, +} +``` + +```go +// Плохо: +repetitive := []*Type{ + &Type{A: 42}, + &Type{A: 43}, +} +``` + +```go +// Хорошо: +good := map[Type1]*Type2{ + {A: 1}: {B: 2}, + {A: 3}: {B: 4}, +} +``` + +```go +// Плохо: +repetitive := map[Type1]*Type2{ + Type1{A: 1}: &Type2{B: 2}, + Type1{A: 3}: &Type2{B: 4}, +} +``` + +**Совет:** Если вы хотите удалить повторяющиеся имена типов в литералах +структур, вы можете запустить `gofmt -s`. + +<a id="literal-zero-value-fields"></a> + +#### Поля с нулевыми значениями + +[Нулевые] поля могут быть опущены в литералах структур, когда ясность не +теряется в результате. + +Хорошо спроектированные API часто используют конструкцию с нулевыми значениями +для улучшенной читаемости. Например, опускание трех полей с нулевыми значениями +из следующей структуры привлекает внимание к единственной опции, которая +указана. + +[Нулевые]: https://golang.org/ref/spec#The_zero_value + +```go +// Плохо: +import ( + "github.com/golang/leveldb" + "github.com/golang/leveldb/db" +) + +ldb := leveldb.Open("/my/table", &db.Options{ + BlockSize: 1<<16, + ErrorIfDBExists: true, + + // Все эти поля имеют свои нулевые значения. + BlockRestartInterval: 0, + Comparer: nil, + Compression: nil, + FileSystem: nil, + FilterPolicy: nil, + MaxOpenFiles: 0, + WriteBufferSize: 0, + VerifyChecksums: false, +}) +``` + +```go +// Хорошо: +import ( + "github.com/golang/leveldb" + "github.com/golang/leveldb/db" +) + +ldb := leveldb.Open("/my/table", &db.Options{ + BlockSize: 1<<16, + ErrorIfDBExists: true, +}) +``` + +Структуры в табличных тестах часто выигрывают от [явных имен полей], особенно +когда тестовая структура нетривиальна. Это позволяет автору опускать поля с +нулевыми значениями полностью, когда рассматриваемые поля не относятся к +тестовому случаю. Например, успешные тестовые случаи должны опускать любые поля, +связанные с ошибками или неудачами. В случаях, когда нулевое значение +необходимо для понимания тестового случая, таких как тестирование нулевых или +`nil` входных данных, имена полей должны быть указаны. + +[явных имен полей]: #literal-field-names + +**Лаконично** + +```go +tests := []struct { + input string + wantPieces []string + wantErr error +}{ + { + input: "1.2.3.4", + wantPieces: []string{"1", "2", "3", "4"}, + }, + { + input: "hostname", + wantErr: ErrBadHostname, + }, +} +``` + +**Явно** + +```go +tests := []struct { + input string + wantIPv4 bool + wantIPv6 bool + wantErr bool +}{ + { + input: "1.2.3.4", + wantIPv4: true, + wantIPv6: false, + }, + { + input: "1:2::3:4", + wantIPv4: false, + wantIPv6: true, + }, + { + input: "hostname", + wantIPv4: false, + wantIPv6: false, + wantErr: true, + }, +} +``` + +<a id="nil-slices"></a> + +### Nil-срезы + +Для большинства целей нет функциональной разницы между `nil` и пустым срезом. +Встроенные функции, такие как `len` и `cap`, ведут себя ожидаемо на `nil` +срезах. + +```go +// Хорошо: +import "fmt" + +var s []int // nil + +fmt.Println(s) // [] +fmt.Println(len(s)) // 0 +fmt.Println(cap(s)) // 0 +for range s {...} // нет операции + +s = append(s, 42) +fmt.Println(s) // [42] +``` + +Если вы объявляете пустой срез как локальную переменную (особенно если она может +быть источником возвращаемого значения), предпочитайте инициализацию nil, чтобы +снизить риск ошибок со стороны вызывающих. + +```go +// Хорошо: +var t []string +``` + +```go +// Плохо: +t := []string{} +``` + +Не создавайте API, которые вынуждают своих клиентов делать различие между nil и +пустым срезом. + +```go +// Хорошо: +// Ping проверяет доступность своих целей. +// Возвращает хосты, которые успешно ответили. +func Ping(hosts []string) ([]string, error) { ... } +``` + +```go +// Плохо: +// Ping проверяет доступность своих целей и возвращает список хостов, +// которые успешно ответили. Может быть пустым, если вход был пустым. +// nil означает, что произошла системная ошибка. +func Ping(hosts []string) []string { ... } +``` + +При проектировании интерфейсов избегайте различия между `nil` срезом и ненулевым +срезом нулевой длины, так как это может привести к тонким программным ошибкам. +Обычно это достигается с помощью `len` для проверки на пустоту, а не `== nil`. + +Эта реализация принимает как `nil`, так и срезы нулевой длины как "пустые": + +```go +// Хорошо: +// describeInts описывает s с заданным префиксом, если s не пуст. +func describeInts(prefix string, s []int) { + if len(s) == 0 { + return + } + fmt.Println(prefix, s) +} +``` + +Вместо того чтобы полагаться на различие как часть API: + +```go +// Плохо: +func maybeInts() []int { /* ... */ } + +// describeInts описывает s с заданным префиксом; передайте nil, чтобы полностью пропустить. +func describeInts(prefix string, s []int) { + // Поведение этой функции непреднамеренно меняется в зависимости от того, что + // возвращает maybeInts() в 'пустых' случаях (nil или []int{}). + if s == nil { + return + } + fmt.Println(prefix, s) +} + +describeInts("Here are some ints:", maybeInts()) +``` + +См. [ошибки "в потоке"] для дальнейшего обсуждения. + +[ошибки "в потоке"]: #in-band-errors + +<a id="indentation-confusion"></a> + +### Путаница с отступами + +Избегайте введения разрыва строки, если это приведет к выравниванию остальной +части строки с вложенным блоком кода. Если этого невозможно избежать, оставьте +пробел, чтобы отделить код в блоке от перенесенной строки. + +```go +// Плохо: +if longCondition1 && longCondition2 && + // Условия 3 и 4 имеют тот же отступ, что и код внутри if. + longCondition3 && longCondition4 { + log.Info("all conditions met") +} +``` + +См. следующие разделы для конкретных рекомендаций и примеров: + +* [Форматирование функций](#func-formatting) +* [Условные операторы и циклы](#conditional-formatting) +* [Форматирование литералов](#literal-formatting) + +<a id="func-formatting"></a> + +### Форматирование функций + +Сигнатура объявления функции или метода должна оставаться на одной строке, чтобы +избежать [путаницы с отступами](#indentation-confusion). + +Списки аргументов функций могут создавать одни из самых длинных строк в файле +исходного кода Go. Однако они предшествуют изменению отступа, и поэтому трудно +разорвать строку так, чтобы последующие строки не выглядели частью тела функции +запутанным образом: + +```go +// Плохо: +func (r *SomeType) SomeLongFunctionName(foo1, foo2, foo3 string, + foo4, foo5, foo6 int) { + foo7 := bar(foo1) + // ... +} +``` + +См. [лучшие практики](https://neonxp.ru/pages/gostyleguide/google/best-practices/#funcargs) для нескольких вариантов +сокращения мест вызовов функций, которые в противном случае имели бы много +аргументов. + +Строки часто можно сократить, вынося локальные переменные. + +```go +// Хорошо: +local := helper(some, parameters, here) +good := foo.Call(list, of, parameters, local) +``` + +Аналогично, вызовы функций и методов не должны разделяться исключительно на +основе длины строки. + +```go +// Хорошо: +good := foo.Call(long, list, of, parameters, all, on, one, line) +``` + +```go +// Плохо: +bad := foo.Call(long, list, of, parameters, + with, arbitrary, line, breaks) +``` + +По возможности избегайте добавления встроенных комментариев к конкретным +аргументам функций. Вместо этого используйте [структуру опций (option +struct)](https://neonxp.ru/pages/gostyleguide/google/best-practices/#option-structure) или добавьте больше деталей в +документацию функции. + +```go +// Хорошо: +good := server.New(ctx, server.Options{Port: 42}) +``` + +```go +// Плохо: +bad := server.New( + ctx, + 42, // Port +) +``` + +Если API нельзя изменить или если локальный вызов необычен (независимо от того, +слишком длинный вызов или нет), всегда допустимо добавлять разрывы строк, если +это помогает понять вызов. + +```go +// Хорошо: +canvas.RenderHeptagon(fillColor, + x0, y0, vertexColor0, + x1, y1, vertexColor1, + x2, y2, vertexColor2, + x3, y3, vertexColor3, + x4, y4, vertexColor4, + x5, y5, vertexColor5, + x6, y6, vertexColor6, +) +``` + +Обратите внимание, что строки в приведенном выше примере не переносятся на +определенную границу столбца, а группируются на основе координат вершин и цвета. + +Длинные строковые литералы внутри функций не должны разбиваться ради длины +строки. Для функций, включающих такие строки, разрыв строки можно добавить +после формата строки, а аргументы могут быть предоставлены на следующей или +последующих строках. Решение о том, где должны быть разрывы строк, лучше всего +принимать на основе семантических групп входных данных, а не исключительно на +основе длины строки. + +```go +// Хорошо: +log.Warningf("Database key (%q, %d, %q) incompatible in transaction started by (%q, %d, %q)", + currentCustomer, currentOffset, currentKey, + txCustomer, txOffset, txKey) +``` + +```go +// Плохо: +log.Warningf("Database key (%q, %d, %q) incompatible in"+ + " transaction started by (%q, %d, %q)", + currentCustomer, currentOffset, currentKey, txCustomer, + txOffset, txKey) +``` + +<a id="conditional-formatting"></a> + +### Условные операторы и циклы + +Оператор `if` не должен разбиваться на строки; многострочные условия `if` могут +привести к [путанице с отступами](#indentation-confusion). + +```go +// Плохо: +// Второй оператор if выровнен с кодом внутри блока if, что вызывает +// путаницу с отступами. +if db.CurrentStatusIs(db.InTransaction) && + db.ValuesEqual(db.TransactionKey(), row.Key()) { + return db.Errorf(db.TransactionError, "query failed: row (%v): key does not match transaction key", row) +} +``` + +Если короткое замыкание не требуется, булевы операнды могут быть извлечены +напрямую: + +```go +// Хорошо: +inTransaction := db.CurrentStatusIs(db.InTransaction) +keysMatch := db.ValuesEqual(db.TransactionKey(), row.Key()) +if inTransaction && keysMatch { + return db.Error(db.TransactionError, "query failed: row (%v): key does not match transaction key", row) +} +``` + +Также могут быть другие локальные переменные, которые можно извлечь, особенно +если условие уже повторяется: + +```go +// Хорошо: +uid := user.GetUniqueUserID() +if db.UserIsAdmin(uid) || db.UserHasPermission(uid, perms.ViewServerConfig) || db.UserHasPermission(uid, perms.CreateGroup) { + // ... +} +``` + +```go +// Плохо: +if db.UserIsAdmin(user.GetUniqueUserID()) || db.UserHasPermission(user.GetUniqueUserID(), perms.ViewServerConfig) || db.UserHasPermission(user.GetUniqueUserID(), perms.CreateGroup) { + // ... +} +``` + +Операторы `if`, содержащие замыкания или многострочные литералы структур, должны +обеспечить, чтобы [скобки совпадали](#literal-matching-braces), чтобы избежать +[путаницы с отступами](#indentation-confusion). + +```go +// Хорошо: +if err := db.RunInTransaction(func(tx *db.TX) error { + return tx.Execute(userUpdate, x, y, z) +}); err != nil { + return fmt.Errorf("user update failed: %s", err) +} +``` + +```go +// Хорошо: +if _, err := client.Update(ctx, &upb.UserUpdateRequest{ + ID: userID, + User: user, +}); err != nil { + return fmt.Errorf("user update failed: %s", err) +} +``` + +Аналогично, не пытайтесь вставлять искусственные разрывы строк в операторы +`for`. Вы всегда можете позволить строке быть просто длинной, если нет +элегантного способа ее рефакторить: + +```go +// Хорошо: +for i, max := 0, collection.Size(); i < max && !collection.HasPendingWriters(); i++ { + // ... +} +``` + +Однако часто он есть: + +```go +// Хорошо: +for i, max := 0, collection.Size(); i < max; i++ { + if collection.HasPendingWriters() { + break + } + // ... +} +``` + +Операторы `switch` и `case` также должны оставаться на одной строке. + +```go +// Хорошо: +switch good := db.TransactionStatus(); good { +case db.TransactionStarting, db.TransactionActive, db.TransactionWaiting: + // ... +case db.TransactionCommitted, db.NoTransaction: + // ... +default: + // ... +} +``` + +```go +// Плохо: +switch bad := db.TransactionStatus(); bad { +case db.TransactionStarting, + db.TransactionActive, + db.TransactionWaiting: + // ... +case db.TransactionCommitted, + db.NoTransaction: + // ... +default: + // ... +} +``` + +Если строка чрезмерно длинная, сделайте отступ для всех вариантов (`case`) и +отделите их пустой строкой, чтобы избежать [путаницы с +отступами](#indentation-confusion): + +```go +// Хорошо: +switch db.TransactionStatus() { +case + db.TransactionStarting, + db.TransactionActive, + db.TransactionWaiting, + db.TransactionCommitted: + + // ... +case db.NoTransaction: + // ... +default: + // ... +} +``` + +В условных выражениях, сравнивающих переменную с константой, помещайте значение +переменной слева от оператора равенства: + +```go +// Хорошо: +if result == "foo" { + // ... +} +``` + +Вместо менее ясной формулировки, где константа идет первой (["условия в стиле +Йоды"](https://en.wikipedia.org/wiki/Yoda_conditions)): + +```go +// Плохо: +if "foo" == result { + // ... +} +``` + +<a id="copying"></a> + +### Копирование + +<a id="TOC-Copying"></a> + +Чтобы избежать неожиданного псевдонимного доступа (aliasing) и подобных ошибок, +будьте осторожны при копировании структуры из другого пакета. Например, объекты +синхронизации, такие как `sync.Mutex`, не должны копироваться. + +Тип `bytes.Buffer` содержит срез `[]byte` и, в качестве оптимизации для +небольших строк, небольшой массив байтов, на который может ссылаться срез. Если +вы скопируете `Buffer`, срез в копии может стать псевдонимом массива в +оригинале, вызывая неожиданные эффекты при последующих вызовах методов. + +В целом, не копируйте значение типа `T`, если его методы ассоциированы с +указательным типом, `*T`. + +```go +// Плохо: +b1 := bytes.Buffer{} +b2 := b1 +``` + +Вызов метода, принимающего получателя по значению, может скрыть копирование. +Когда вы создаете API, вам обычно следует принимать и возвращать типы-указатели, +если ваши структуры содержат поля, которые не должны копироваться. + +Эти примеры допустимы: + +```go +// Хорошо: +type Record struct { + buf bytes.Buffer + // другие поля опущены +} + +func New() *Record {...} + +func (r *Record) Process(...) {...} + +func Consumer(r *Record) {...} +``` + +Но эти обычно ошибочны: + +```go +// Плохо: +type Record struct { + buf bytes.Buffer + // другие поля опущены +} + + +func (r Record) Process(...) {...} // Создает копию r.buf + +func Consumer(r Record) {...} // Создает копию r.buf +``` + +Эти рекомендации также применимы к копированию `sync.Mutex`. + +<a id="dont-panic"></a> + +### Не используйте panic + +<a id="TOC-Don-t-Panic"></a> + +Не используйте `panic` для обычной обработки ошибок. Вместо этого используйте +`error` и множественные возвращаемые значения. См. [раздел Effective Go об +ошибках]. + +В `package main` и коде инициализации рассмотрите [`log.Exit`] для ошибок, +которые должны завершать программу (например, неверная конфигурация), поскольку +во многих из этих случаев трассировка стека не поможет читателю. Обратите +внимание, что [`log.Exit`] вызывает [`os.Exit`] и отложенные (deferred) функции +не будут выполнены. + +Для ошибок, указывающих на "невозможные" условия, а именно на ошибки, которые +всегда должны быть обнаружены при проверке кода и/или тестировании, функция +может разумно вернуть ошибку или вызвать [`log.Fatal`]. + +Также см. [когда panic допустим](https://neonxp.ru/pages/gostyleguide/google/best-practices/.md#when-to-panic). + +**Примечание:** `log.Fatalf` здесь не из стандартной библиотеки log. См. +[#logging]. + +[раздел Effective Go об ошибках]: http://golang.org/doc/effective_go.html#errors +[`os.Exit`]: https://pkg.go.dev/os#Exit + +<a id="must-functions"></a> + +### Функции Must + +Вспомогательные функции настройки, которые останавливают программу при неудаче, +следуют соглашению об именовании `MustXYZ` (или `mustXYZ`). Как правило, их +следует вызывать только на раннем этапе запуска программы, а не для таких вещей, +как пользовательский ввод, где предпочтительна обычная обработка ошибок Go. + +Это часто возникает для функций, вызываемых для инициализации переменных уровня +пакета исключительно во время [инициализации +пакета](https://golang.org/ref/spec#Package_initialization) (например, +[template.Must](https://golang.org/pkg/text/template/#Must) и +[regexp.MustCompile](https://golang.org/pkg/regexp/#MustCompile)). + +```go +// Хорошо: +func MustParse(version string) *Version { + v, err := Parse(version) + if err != nil { + panic(fmt.Sprintf("MustParse(%q) = _, %v", version, err)) + } + return v +} + +// "Константа" уровня пакета. Если бы мы хотели использовать `Parse`, нам пришлось бы +// устанавливать значение в `init`. +var DefaultVersion = MustParse("1.2.3") +``` + +То же соглашение может использоваться во вспомогательных функциях тестирования, +которые останавливают только текущий тест (используя `t.Fatal`). Такие помощники +часто удобны при создании тестовых значений, например, в полях структур +[табличных тестов](#table-driven-tests), поскольку функции, возвращающие ошибки, +не могут быть напрямую присвоены полю структуры. + +```go +// Хорошо: +func mustMarshalAny(t *testing.T, m proto.Message) *anypb.Any { + t.Helper() + any, err := anypb.New(m) + if err != nil { + t.Fatalf("mustMarshalAny(t, m) = %v; want %v", err, nil) + } + return any +} + +func TestCreateObject(t *testing.T) { + tests := []struct{ + desc string + data *anypb.Any + }{ + { + desc: "my test case", + // Создание значений непосредственно внутри тестовых случаев табличного теста. + data: mustMarshalAny(t, mypb.Object{}), + }, + // ... + } + // ... +} +``` + +В обоих этих случаях ценность этого шаблона в том, что помощники могут быть +вызваны в "знаковом" контексте. Этих помощников не следует вызывать в местах, +где трудно обеспечить перехват ошибки, или в контексте, где ошибка должна быть +[проверена](#handle-errors) (например, во многих обработчиках запросов). Для +постоянных входных данных это позволяет тестам легко убедиться, что аргументы +`Must` корректны, а для непостоянных входных данных это позволяет тестам +проверять, что ошибки [правильно обработаны или +распространены](https://neonxp.ru/pages/gostyleguide/google/best-practices/#error-handling). + +Где функции `Must` используются в тесте, их обычно следует [помечать как +тестовый помощник](#mark-test-helpers) и вызывать `t.Fatal` при ошибке (см. +[обработка ошибок во вспомогательных тестовых +функциях](https://neonxp.ru/pages/gostyleguide/google/best-practices/#test-helper-error-handling) для дополнительных +соображений по использованию этого). + +Их не следует использовать, когда [обычная обработка +ошибок](https://neonxp.ru/pages/gostyleguide/google/best-practices/#error-handling) возможна (включая некоторый рефакторинг): + +```go +// Плохо: +func Version(o *servicepb.Object) (*version.Version, error) { + // Вернуть ошибку вместо использования функций Must. + v := version.MustParse(o.GetVersionString()) + return dealiasVersion(v) +} +``` + +<a id="goroutine-lifetimes"></a> + +### Время жизни горутин + +<a id="TOC-GoroutineLifetimes"></a> + +Когда вы порождаете горутины, сделайте ясным, когда или завершаются ли они. + +Горутины могут "подтекать", блокируясь на отправке или получении по каналу. +Сборщик мусора не завершит горутину, заблокированную на канале, даже если +никакая другая горутина не имеет ссылки на этот канал. + +Даже когда горутины не подтекают, оставлять их активными, когда они больше не +нужны, может вызвать другие тонкие и трудные для диагностики проблемы. Отправка +в закрытый канал вызывает панику. + +```go +// Плохо: +ch := make(chan int) +ch <- 42 +close(ch) +ch <- 13 // panic +``` + +Изменение все еще используемых входных данных "после того, как результат не +нужен", может привести к гонкам данных. Оставление горутин активными на +произвольное время может привести к непредсказуемому использованию памяти. + +Параллельный код должен быть написан так, чтобы время жизни горутин было +очевидным. Обычно это означает сохранение кода, связанного с синхронизацией, в +пределах области видимости функции и вынесение логики в [синхронные функции]. +Если параллелизм все еще не очевиден, важно задокументировать, когда и почему +горутины завершаются. + +Код, следующий лучшим практикам использования контекста, часто помогает +прояснить это. Обычно это управляется с помощью [`context.Context`]: + +```go +// Хорошо: +func (w *Worker) Run(ctx context.Context) error { + var wg sync.WaitGroup + // ... + for item := range w.q { + // process возвращается самое позднее при отмене контекста. + wg.Add(1) + go func() { + defer wg.Done() + process(ctx, item) + }() + } + // ... + wg.Wait() // Предотвращает переживание порожденными горутинами этой функции. +} +``` + +Существуют другие варианты вышеизложенного, использующие простые сигнальные +каналы, такие как `chan struct{}`, синхронизированные переменные, [условные +переменные][rethinking-slides] и многое другое. Важная часть заключается в том, +что конец горутины очевиден для последующих сопровождающих. + +В отличие от этого, следующий код небрежен в отношении того, когда его +порожденные горутины завершаются: + +```go +// Плохо: +func (w *Worker) Run() { + // ... + for item := range w.q { + // process возвращается, когда завершается, если вообще завершится, возможно, не обрабатывая корректно + // переход состояния или завершение самой программы Go. + go process(item) + } + // ... +} +``` + +Этот код может выглядеть нормально, но у него есть несколько скрытых проблем: + +* Код, вероятно, имеет неопределенное поведение в продакшене, и программа + может не завершиться чисто, даже если операционная система освободит + ресурсы. + +* Код трудно осмысленно протестировать из-за неопределенного жизненного цикла. + +* Код может подтекать ресурсами, как описано выше. + +См. также: + +* [Никогда не запускайте горутину, не зная, как она остановится][cheney-stop] +* Переосмысление классических паттернов параллелизма: + [слайды][rethinking-slides], [видео][rethinking-video] +* [Когда программы на Go завершаются] +* [Соглашения по документации: Контексты] + +[синхронные функции]: #synchronous-functions +[cheney-stop]: + https://dave.cheney.net/2016/12/22/never-start-a-goroutine-without-knowing-how-it-will-stop +[rethinking-slides]: + https://drive.google.com/file/d/1nPdvhB0PutEJzdCq5ms6UI58dp50fcAN/view +[rethinking-video]: https://www.youtube.com/watch?v=5zXAHh5tJqQ +[Когда программы на Go завершаются]: https://changelog.com/gotime/165 +[Соглашения по документации: Контексты]: + best-practices.md#documentation-conventions-contexts + +<a id="interfaces"></a> + +### Интерфейсы + +<a id="TOC-Interfaces"></a> + +Интерфейсы Go обычно принадлежат пакету, который *потребляет* значения типа +интерфейса, а не пакету, который *реализует* тип интерфейса. Реализующий пакет +должен возвращать конкретные (обычно указатель или структура) типы. Таким +образом, новые методы могут быть добавлены к реализациям без необходимости +обширного рефакторинга. Подробнее см. [GoTip #49: Принимайте интерфейсы, +возвращайте конкретные типы]. + +Не экспортируйте [тестовый дубль (test double)][double types] реализации +интерфейса из API, который его потребляет. Вместо этого спроектируйте API так, +чтобы его можно было тестировать с помощью [публичного API] [реальной +реализации]. См. [GoTip #42: Создание заглушки для тестирования] для +подробностей. Даже когда нецелесообразно использовать реальную реализацию, может +не потребоваться вводить интерфейс, полностью покрывающий все методы в реальном +типе; потребитель может создать интерфейс, содержащий только нужные ему методы, +как показано в [GoTip #78: Минимально жизнеспособные интерфейсы]. + +Для тестирования пакетов, использующих Stubby RPC клиенты, используйте реальное +клиентское соединение. Если реальный сервер не может быть запущен в тесте, +внутренняя практика Google — получить реальное клиентское соединение с локальным +[тестовым дублем] с использованием внутреннего пакета rpctest (скоро будет!). + +Не определяйте интерфейсы до того, как они используются (см. [TotT: Code +Health: Eliminate YAGNI Smells][tott-438] ). Без реалистичного примера +использования слишком сложно увидеть, нужен ли интерфейс вообще, не говоря уже о +том, какие методы он должен содержать. + +Не используйте параметры типа интерфейса, если пользователям пакета не нужно +передавать различные типы для них. + +Не экспортируйте интерфейсы, которые не нужны пользователям пакета. + +**TODO:** Написать более подробный документ об интерфейсах и дать на него ссылку +здесь. + +[GoTip #42: Создание заглушки для тестирования]: + https://google.github.io/styleguide/go/index.html#gotip +[GoTip #49: Принимайте интерфейсы, возвращайте конкретные типы]: + https://google.github.io/styleguide/go/index.html#gotip +[GoTip #78: Минимально жизнеспособные интерфейсы]: + https://google.github.io/styleguide/go/index.html#gotip +[реальной реализации]: best-practices#use-real-transports +[публичному API]: + https://abseil.io/resources/swe-book/html/ch12.html#test_via_public_apis +[double types]: + https://abseil.io/resources/swe-book/html/ch13.html#techniques_for_using_test_doubles +[тестовым дублем]: + https://abseil.io/resources/swe-book/html/ch13.html#basic_concepts +[tott-438]: + https://testing.googleblog.com/2017/08/code-health-eliminate-yagni-smells.html + +```go +// Хорошо: +package consumer // consumer.go + +type Thinger interface { Thing() bool } + +func Foo(t Thinger) string { ... } +``` + +```go +// Хорошо: +package consumer // consumer_test.go + +type fakeThinger struct{ ... } +func (t fakeThinger) Thing() bool { ... } +... +if Foo(fakeThinger{...}) == "x" { ... } +``` + +```go +// Плохо: +package producer + +type Thinger interface { Thing() bool } + +type defaultThinger struct{ ... } +func (t defaultThinger) Thing() bool { ... } + +func NewThinger() Thinger { return defaultThinger{ ... } } +``` + +```go +// Хорошо: +package producer + +type Thinger struct{ ... } +func (t Thinger) Thing() bool { ... } + +func NewThinger() Thinger { return Thinger{ ... } } +``` + +<a id="generics"></a> + +### Дженерики (Generics) + +Дженерики (формально называемые "[Параметрами типа]") разрешены там, где они +удовлетворяют вашим бизнес-требованиям. Во многих приложениях обычный подход с +использованием существующих языковых возможностей (срезы, карты, интерфейсы и +т.д.) работает так же хорошо без добавленной сложности, поэтому будьте осторожны +с преждевременным использованием. См. обсуждение [наименьшего механизма (least +mechanism)](https://neonxp.ru/pages/gostyleguide/google/guide/#least-mechanism). + +При введении экспортируемого API, использующего дженерики, убедитесь, что он +должным образом задокументирован. Настоятельно рекомендуется включать +мотивирующие исполняемые [примеры]. + +Не используйте дженерики только потому, что вы реализуете алгоритм или структуру +данных, которой не важен тип элементов. Если на практике инстанцируется только +один тип, начните с того, чтобы ваш код работал с этим типом без использования +дженериков вообще. Добавить полиморфизм позже будет проще по сравнению с +удалением абстракции, которая оказывается ненужной. + +Не используйте дженерики для создания предметно-ориентированных языков (DSL). В +частности, воздержитесь от введения фреймворков обработки ошибок, которые могут +значительно обременять читателей. Вместо этого предпочитайте установленные +методы [обработки ошибок](#errors). Для тестирования особенно остерегайтесь +введения [библиотек утверждений (assertion libraries)](#assert) или фреймворков, +которые приводят к менее полезным [сообщениям об ошибках +тестов](#useful-test-failures). + +В общем: + +* [Пишите код, не проектируйте типы]. Из выступления на GopherCon от Роберта + Грисемера и Яна Лэнса Тейлора. +* Если у вас есть несколько типов, которые разделяют полезный объединяющий + интерфейс, рассмотрите моделирование решения с использованием этого + интерфейса. Дженерики могут не понадобиться. +* В противном случае вместо того, чтобы полагаться на тип `any` и чрезмерное + [переключение типов (type switching)](https://tour.golang.org/methods/16), + рассмотрите дженерики. + +См. также: + +* [Использование дженериков в Go], выступление Яна Лэнса Тейлора + +* [Учебник по дженерикам] на сайте Go + +[Учебник по дженерикам]: https://go.dev/doc/tutorial/generics +[Параметрами типа]: https://go.dev/design/43651-type-parameters +[Использование дженериков в Go]: https://www.youtube.com/watch?v=nr8EpUO9jhw +[Пишите код, не проектируйте типы]: + https://www.youtube.com/watch?v=Pa_e9EeCdy8&t=1250s + +<a id="pass-values"></a> + +### Передача по значению + +<a id="TOC-PassValues"></a> + +Не передавайте указатели в качестве аргументов функций только для экономии +нескольких байтов. Если функция читает свой аргумент `x` только как `*x` на всем +протяжении, то аргумент не должен быть указателем. Распространенные примеры +этого включают передачу указателя на строку (`*string`) или указателя на +значение интерфейса (`*io.Reader`). В обоих случаях само значение имеет +фиксированный размер и может быть передано напрямую. + +Этот совет не применим к большим структурам или даже малым структурам, которые +могут увеличиться в размере. В частности, сообщения protocol buffer обычно +следует обрабатывать по указателю, а не по значению. Тип-указатель удовлетворяет +интерфейсу `proto.Message` (принимаемому `proto.Marshal`, `protocmp.Transform`, +и т.д.), а сообщения protocol buffer могут быть довольно большими и часто +увеличиваются со временем. + +<a id="receiver-type"></a> + +### Тип получателя (Receiver) + +<a id="TOC-ReceiverType"></a> + +[Получатель метода] может быть передан либо по значению, либо по указателю, как +если бы он был обычным параметром функции. Выбор между ними основан на том, в +составе какого [набора методов] метод должен находиться. + +[Получатель метода]: https://golang.org/ref/spec#Method_declarations +[набора методов]: https://golang.org/ref/spec#Method_sets + +**Корректность важнее скорости или простоты.** Бывают случаи, когда вы должны +использовать значение-указатель. В других случаях выбирайте указатели для +больших типов или в качестве будущего доказательства, если у вас нет хорошего +понимания того, как будет расти код, и используйте значения для простых [простых +старых данных]. + +Список ниже подробно описывает каждый случай: + +* Если получатель является срезом и метод не переслаивает (reslice) и не + перераспределяет (reallocate) срез, используйте значение, а не указатель. + + ```go + // Хорошо: + type Buffer []byte + + func (b Buffer) Len() int { return len(b) } + ``` + +* Если методу нужно мутировать получателя, получатель должен быть указателем. + + ```go + // Хорошо: + type Counter int + + func (c *Counter) Inc() { *c++ } + + // См. https://pkg.go.dev/container/heap. + type Queue []Item + + func (q *Queue) Push(x Item) { *q = append([]Item{x}, *q...) } + ``` + +* Если получатель является структурой, содержащей поля, которые [не могут быть + безопасно скопированы](#copying), используйте получатель-указатель. + Распространенные примеры — [`sync.Mutex`] и другие типы синхронизации. + + ```go + // Хорошо: + type Counter struct { + mu sync.Mutex + total int + } + + func (c *Counter) Inc() { + c.mu.Lock() + defer c.mu.Unlock() + c.total++ + } + ``` + + **Совет:** Проверьте [Godoc] типа для информации о том, безопасно ли или + небезопасно его копировать. + +* Если получатель является "большой" структурой или массивом, + получатель-указатель может быть более эффективным. Передача структуры + эквивалентна передаче всех ее полей или элементов в качестве аргументов + методу. Если это кажется слишком большим для [передачи по + значению](#pass-values), указатель — хороший выбор. + +* Для методов, которые будут вызываться или выполняться параллельно с другими + функциями, которые изменяют получателя, используйте значение, если эти + изменения не должны быть видны вашему методу; в противном случае используйте + указатель. + +* Если получатель является структурой или массивом, любой элемент которого + является указателем на что-то, что может быть изменено, предпочтите + получателя-указателя, чтобы сделать намерение изменяемости понятным для + читателя. + + ```go + // Хорошо: + type Counter struct { + m *Metric + } + + func (c *Counter) Inc() { + c.m.Add(1) + } + ``` + +* Если получатель является [встроенным типом], таким как целое число или + строка, который не нужно изменять, используйте значение. + + ```go + // Хорошо: + type User string + + func (u User) String() { return string(u) } + ``` + +* Если получатель является картой (map), функцией или каналом, используйте + значение, а не указатель. + + ```go + // Хорошо: + // См. https://pkg.go.dev/net/http#Header. + type Header map[string][]string + + func (h Header) Add(key, value string) { /* опущено */ } + ``` + +* Если получатель является "маленьким" массивом или структурой, которые + естественным образом являются типом значения без изменяемых полей и без + указателей, получатель по значению обычно является правильным выбором. + + ```go + // Хорошо: + // См. https://pkg.go.dev/time#Time. + type Time struct { /* опущено */ } + + func (t Time) Add(d Duration) Time { /* опущено */ } + ``` + +* В случае сомнений используйте получатель-указатель. + +В качестве общего руководства предпочитайте, чтобы методы для типа были либо все +указательными методами, либо всеми методами по значению. + +**Примечание:** Существует много дезинформации о том, может ли передача значения +или указателя в функцию повлиять на производительность. Компилятор может выбрать +передачу указателей на значения в стеке, а также копирование значений в стеке, +но эти соображения не должны перевешивать читаемость и корректность кода в +большинстве обстоятельств. Когда производительность действительно имеет +значение, важно профилировать оба подхода с реалистичным бенчмарком, прежде чем +решать, что один подход превосходит другой. + +[простых старых данных]: https://en.wikipedia.org/wiki/Passive_data_structure +[`sync.Mutex`]: https://pkg.go.dev/sync#Mutex +[встроенным типом]: https://pkg.go.dev/builtin + +<a id="switch-break"></a> + +### `switch` и `break` + +<a id="TOC-SwitchBreak"></a> + +Не используйте операторы `break` без целевых меток в конце предложений `switch`; +они избыточны. В отличие от C и Java, предложения `switch` в Go автоматически +завершаются, и для достижения поведения в стиле C требуется оператор +`fallthrough`. Используйте комментарий, а не `break`, если хотите прояснить цель +пустого предложения. + +```go +// Хорошо: +switch x { +case "A", "B": + buf.WriteString(x) +case "C": + // обрабатывается вне оператора switch +default: + return fmt.Errorf("unknown value: %q", x) +} +``` + +```go +// Плохо: +switch x { +case "A", "B": + buf.WriteString(x) + break // этот break избыточен +case "C": + break // этот break избыточен +default: + return fmt.Errorf("unknown value: %q", x) +} +``` + +> **Примечание:** Если предложение `switch` находится внутри цикла `for`, +> использование `break` внутри `switch` не выходит из охватывающего цикла `for`. +> +> ```go +> for { +> switch x { +> case "A": +> break // выходит из switch, не из цикла +> } +> } +> ``` +> +> Чтобы выйти из охватывающего цикла, используйте метку на операторе `for`: +> +> ```go +> loop: +> for { +> switch x { +> case "A": +> break loop // выходит из цикла +> } +> } +> ``` + +<a id="synchronous-functions"></a> + +### Синхронные функции + +<a id="TOC-SynchronousFunctions"></a> + +Синхронные функции возвращают свои результаты напрямую и завершают любые +обратные вызовы или операции с каналами перед возвратом. Предпочитайте +синхронные функции асинхронным. + +Синхронные функции сохраняют горутины локализованными внутри вызова. Это +помогает рассуждать об их времени жизни и избегать утечек и гонок данных. +Синхронные функции также легче тестировать, поскольку вызывающая сторона может +передать входные данные и проверить выходные без необходимости опроса или +синхронизации. + +При необходимости вызывающая сторона может добавить параллелизм, вызвав функцию +в отдельной горутине. Однако довольно сложно (иногда невозможно) убрать ненужный +параллелизм на стороне вызывающего. + +См. также: + +* "Переосмысление классических паттернов параллелизма", выступление Брайана + Миллса: [слайды][rethinking-slides], [видео][rethinking-video] + +<a id="type-aliases"></a> + +### Псевдонимы типов (Type aliases) + +<a id="TOC-TypeAliases"></a> + +Используйте *определение типа*, `type T1 T2`, чтобы определить новый тип. +Используйте [*псевдоним типа*], `type T1 = T2`, чтобы ссылаться на существующий +тип без определения нового типа. Псевдонимы типов редки; их основное +использование — помочь в переносе пакетов в новые места исходного кода. Не +используйте псевдонимы типов, когда это не нужно. + +[*псевдоним типа*]: http://golang.org/ref/spec#Type_declarations + +<a id="use-percent-q"></a> + +### Используйте %q + +<a id="TOC-UsePercentQ"></a> + +Функции форматирования Go (`fmt.Printf` и т.д.) имеют глагол `%q`, который +печатает строки внутри двойных кавычек. + +```go +// Хорошо: +fmt.Printf("value %q looks like English text", someText) +``` + +Предпочитайте использование `%q` вместо эквивалентного ручного способа с +использованием `%s`: + +```go +// Плохо: +fmt.Printf("value \"%s\" looks like English text", someText) +// Также избегайте вручную оборачивать строки одинарными кавычками: +fmt.Printf("value '%s' looks like English text", someText) +``` + +Использование `%q` рекомендуется в выводе, предназначенном для людей, где +входное значение может быть пустым или содержать управляющие символы. Тихую +пустую строку заметить очень сложно, но `""` явно выделяется как таковая. + +<a id="use-any"></a> + +### Используйте any + +Go 1.18 вводит тип `any` как [псевдоним] для `interface{}`. Поскольку это +псевдоним, `any` эквивалентен `interface{}` во многих ситуациях, а в других +легко взаимозаменяем через явное преобразование. Предпочитайте использовать +`any` в новом коде. + +[псевдоним]: + https://go.googlesource.com/proposal/+/master/design/18130-type-alias.md + +## Общие библиотеки + +<a id="flags"></a> + +### Флаги + +<a id="TOC-Flags"></a> + +Программы Go в кодовой базе Google используют внутренний вариант [стандартного +пакета `flag`]. Он имеет схожий интерфейс, но хорошо взаимодействует с +внутренними системами Google. Имена флагов в бинарных файлах Go должны +предпочитать использование подчеркиваний для разделения слов, хотя переменные, +хранящие значение флага, должны следовать стандартному стилю именования Go +([mixed caps]). Конкретно, имя флага должно быть в змеином регистре +(snake_case), а имя переменной должно быть эквивалентным именем в верблюжьем +регистре (camelCase). + +```go +// Хорошо: +var ( + pollInterval = flag.Duration("poll_interval", time.Minute, "Interval to use for polling.") +) +``` + +```go +// Плохо: +var ( + poll_interval = flag.Int("pollIntervalSeconds", 60, "Interval to use for polling in seconds.") +) +``` + +Флаги должны определяться только в `package main` или эквивалентном. + +Универсальные пакеты должны настраиваться с использованием API Go, а не путем +пробивания до интерфейса командной строки; не позволяйте импорту библиотеки +экспортировать новые флаги как побочный эффект. То есть предпочитайте явные +аргументы функций или присваивание полей структуры или, что гораздо реже и под +самым строгим контролем, экспортируемые глобальные переменные. В крайне редком +случае, когда необходимо нарушить это правило, имя флага должно четко указывать +пакет, который он настраивает. + +Если ваши флаги являются глобальными переменными, поместите их в свою +собственную группу `var`, следующую после раздела импортов. + +Существуют дополнительные обсуждения о лучших практиках создания [сложных CLI] с +подкомандами. + +См. также: + +* [Tip of the Week #45: Avoid Flags, Especially in Library Code][totw-45] +* [Go Tip #10: Configuration Structs and + Flags](https://google.github.io/styleguide/go/index.html#gotip) +* [Go Tip #80: Dependency Injection + Principles](https://google.github.io/styleguide/go/index.html#gotip) + +[стандартного пакета `flag`]: https://golang.org/pkg/flag/ +[mixed caps]: guide#mixed-caps +[сложных CLI]: best-practices#complex-clis +[totw-45]: https://abseil.io/tips/45 + +<a id="logging"></a> + +### Логирование + +Программы Go в кодовой базе Google используют вариант стандартного [`log`] +пакета. Он имеет схожий, но более мощный интерфейс и хорошо взаимодействует с +внутренними системами Google. Пакет с открытым исходным кодом этой библиотеки +доступен как [пакет `glog`], и проекты Google с открытым исходным кодом могут +использовать его, но в этом руководстве он повсюду упоминается как `log`. + +**Примечание:** Для аномальных завершений программы эта библиотека использует +`log.Fatal` для аварийного завершения с трассировкой стека и `log.Exit` для +остановки без нее. Здесь нет `log.Panic` функции, как в стандартной библиотеке. + +**Совет:** `log.Info(v)` эквивалентно `log.Infof("%v", v)`, и то же самое +относится к другим уровням логирования. Предпочитайте версию без форматирования, +когда вам нечего форматировать. + +См. также: + +* Лучшие практики по [логированию ошибок](https://neonxp.ru/pages/gostyleguide/google/best-practices/#error-logging) и + [пользовательским уровням детализации (verbosity + levels)](https://neonxp.ru/pages/gostyleguide/google/best-practices/#vlog) +* Когда и как использовать пакет log для [остановки + программы](https://neonxp.ru/pages/gostyleguide/google/best-practices/#checks-and-panics) + +[`log`]: https://pkg.go.dev/log +[`log/slog`]: https://pkg.go.dev/log/slog +[пакет `glog`]: https://pkg.go.dev/github.com/golang/glog +[`log.Exit`]: https://pkg.go.dev/github.com/golang/glog#Exit +[`log.Fatal`]: https://pkg.go.dev/github.com/golang/glog#Fatal + +<a id="contexts"></a> + +### Контексты (Contexts) + +<a id="TOC-Contexts"></a> + +Значения типа [`context.Context`] несут учетные данные безопасности, информацию +трассировки, сроки и сигналы отмены через границы API и процессов. В отличие от +C++ и Java, которые в кодовой базе Google используют локальное хранилище потоков +(thread-local storage), программы Go передают контексты явно вдоль всей цепочки +вызовов функций от входящих RPC и HTTP запросов к исходящим запросам. + +[`context.Context`]: https://pkg.go.dev/context + +При передаче в функцию или метод [`context.Context`] всегда является первым +параметром. + +```go +func F(ctx context.Context /* другие аргументы */) {} +``` + +Исключения: + +* В HTTP обработчике, где контекст берется из + [`req.Context()`](https://pkg.go.dev/net/http#Request.Context). +* В потоковых RPC методах, где контекст берется из потока. + + Код, использующий потоковый gRPC, получает контекст из метода `Context()` в + сгенерированном типе сервера, который реализует `grpc.ServerStream`. См. + [документацию по сгенерированному коду + gRPC](https://grpc.io/docs/languages/go/generated-code/). + +* В точках входа (entrypoint functions) (см. ниже примеры таких функций) + используйте [`context.Background()`] или, для тестов, + [`tb.Context()`](https://pkg.go.dev/testing#TB.Context). + + * В бинарных целях: `main` + * В общем коде и библиотеках: `init` + * В тестах: `TestXXX`, `BenchmarkXXX`, `FuzzXXX` + +> **Примечание**: Очень редко код в середине цепочки вызовов требует создания +> базового контекста самостоятельно с помощью [`context.Background()`]. Всегда +> предпочитайте брать контекст у вашего вызывающего, если это не неправильный +> контекст. +> +> Вы можете столкнуться с серверными библиотеками (реализация Stubby, gRPC или +> HTTP во фреймворке сервера Google для Go), которые создают новый объект +> контекста для каждого запроса. Эти контексты сразу заполняются информацией из +> входящего запроса, так что при передаче в обработчик запроса прикрепленные +> значения контекста были распространены к нему через сетевую границу от +> клиента-вызывающего. Более того, время жизни этих контекстов ограничено +> временем запроса: когда запрос завершен, контекст отменяется. +> +> Если вы не реализуете серверный фреймворк, вы не должны создавать контексты с +> помощью [`context.Background()`] в библиотечном коде. Вместо этого +> предпочитайте использование отсоединения контекста (context detachment), +> которое упоминается ниже, если доступен существующий контекст. Если вы +> думаете, что вам действительно нужно [`context.Background()`] вне функций +> точек входа, обсудите это со списком рассылки Google Go style, прежде чем +> приступать к реализации. + +Соглашение о том, что [`context.Context`] идет первым в функциях, также +применимо к тестовым помощникам. + +```go +// Хорошо: +func readTestFile(ctx context.Context, t *testing.T, path string) string {} +``` + +Не добавляйте поле context в тип структуры. Вместо этого добавьте параметр +context в каждый метод типа, которому нужно передавать его дальше. Единственное +исключение — для методов, чья сигнатура должна соответствовать интерфейсу в +стандартной библиотеке или в сторонней библиотеке вне контроля Google. Такие +случаи очень редки и должны быть обсуждены со списком рассылки Google Go style +до реализации и проверки на читаемость. + +**Примечание:** Go 1.24 добавил метод [`(testing.TB).Context()`]. В тестах +предпочитайте использовать [`(testing.TB).Context()`] вместо +[`context.Background()`] для предоставления начального [`context.Context`], +используемого тестом. Вспомогательные функции, настройка окружения или тестовых +дублей и другие функции, вызываемые из тела тестовой функции, которые требуют +контекст, должны иметь его явно переданным. + +[`(testing.TB).Context()`]: https://pkg.go.dev/testing#TB.Context + +Код в кодовой базе Google, который должен порождать фоновые операции, способные +выполняться после отмены родительского контекста, может использовать внутренний +пакет для отсоединения. Следите за [issue +#40221](https://github.com/golang/go/issues/40221) для обсуждений об +альтернативе с открытым исходным кодом. + +Поскольку контексты неизменяемы, нормально передавать один и тот же контекст в +несколько вызовов, которые разделяют один и тот же дедлайн, сигнал отмены, +учетные данные, родительскую трассировку и т.д. + +См. также: + +* [Контексты и структуры] + +[`context.Background()`]: https://pkg.go.dev/context/#Background +[Контексты и структуры]: https://go.dev/blog/context-and-structs + +<a id="custom-contexts"></a> + +#### Пользовательские контексты + +Не создавайте пользовательские типы контекстов и не используйте интерфейсы, +отличные от [`context.Context`], в сигнатурах функций. Для этого правила нет +исключений. + +Представьте, если бы каждая команда имела свой пользовательский контекст. Каждый +вызов функции из пакета `p` в пакет `q` должен был бы определять, как +преобразовать `p.Context` в `q.Context`, для всех пар пакетов `p` и `q`. Это +нецелесообразно и создает ошибки для людей, и это делает автоматизированные +рефакторинги, добавляющие параметры контекста, почти невозможными. + +Если у вас есть данные приложения для передачи, поместите их в параметр, в +получателе, в глобальных переменных или в значении `Context`, если они +действительно принадлежат там. Создание вашего собственного типа контекста +неприемлемо, поскольку оно подрывает способность команды Go заставить программы +Go правильно работать в продакшене. + +<a id="crypto-rand"></a> + +### crypto/rand + +<a id="TOC-CryptoRand"></a> + +Не используйте пакет `math/rand` для генерации ключей, даже одноразовых. Если не +задано начальное значение (seed), генератор полностью предсказуем. При задании +начального значения `time.Nanoseconds()` существует всего несколько бит +энтропии. Вместо этого используйте `Reader` из `crypto/rand`, и если вам нужен +текст, выводите в шестнадцатеричном или base64. + +```go +// Хорошо: +import ( + "crypto/rand" + // "encoding/base64" + // "encoding/hex" + "fmt" + + // ... +) + +func Key() string { + buf := make([]byte, 16) + if _, err := rand.Read(buf); err != nil { + log.Fatalf("Out of randomness, should never happen: %v", err) + } + return fmt.Sprintf("%x", buf) + // или hex.EncodeToString(buf) + // или base64.StdEncoding.EncodeToString(buf) +} +``` + +**Примечание:** `log.Fatalf` здесь не из стандартной библиотеки log. См. +[#logging]. + +<a id="useful-test-failures"></a> + +## Полезные сообщения об ошибках тестов + +<a id="TOC-UsefulTestFailures"></a> + +Должна быть возможность диагностировать неудачу теста без чтения исходного кода +теста. Тесты должны завершаться неудачей с полезными сообщениями, +детализирующими: + +* Что вызвало неудачу +* Какие входные данные привели к ошибке +* Фактический результат +* Что ожидалось + +Конкретные соглашения для достижения этой цели изложены ниже. + +<a id="assert"></a> + +### Библиотеки утверждений (Assertion libraries) + +<a id="TOC-Assert"></a> + +Не создавайте "библиотеки утверждений" в качестве помощников для тестирования. + +Библиотеки утверждений — это библиотеки, которые пытаются объединить проверку и +формирование сообщений об ошибках в тесте (хотя те же ловушки могут применяться +и к другим тестовым помощникам). Подробнее о различии между тестовыми +помощниками и библиотеками утверждений см. [лучшие +практики](https://neonxp.ru/pages/gostyleguide/google/best-practices/#test-functions). + +```go +// Плохо: +var obj BlogPost + +assert.IsNotNil(t, "obj", obj) +assert.StringEq(t, "obj.Type", obj.Type, "blogPost") +assert.IntEq(t, "obj.Comments", obj.Comments, 2) +assert.StringNotEq(t, "obj.Body", obj.Body, "") +``` + +Библиотеки утверждений имеют тенденцию либо останавливать тест рано (если +`assert` вызывает `t.Fatalf` или `panic`), либо опускать соответствующую +информацию о том, что тест получил правильно: + +```go +// Плохо: +package assert + +func IsNotNil(t *testing.T, name string, val any) { + if val == nil { + t.Fatalf("Data %s = nil, want not nil", name) + } +} + +func StringEq(t *testing.T, name, got, want string) { + if got != want { + t.Fatalf("Data %s = %q, want %q", name, got, want) + } +} +``` + +Сложные функции утверждений часто не предоставляют [полезные сообщения об +ошибках] и контекст, существующий внутри тестовой функции. Слишком много функций +утверждений и библиотек приводит к фрагментированному опыту разработчика: какую +библиотеку утверждений использовать, какой стиль формата вывода она должна +выдавать и т.д.? Фрагментация создает ненужную путаницу, особенно для +сопровождающих библиотек и авторов крупномасштабных изменений, которые отвечают +за исправление потенциальных поломок вниз по течению. Вместо создания +предметно-ориентированного языка для тестирования используйте сам Go. + +Библиотеки утверждений часто выносят сравнения и проверки равенства. +Предпочитайте использование стандартных библиотек, таких как [`cmp`] и [`fmt`], +вместо этого: + +```go +// Хорошо: +var got BlogPost + +want := BlogPost{ + Comments: 2, + Body: "Hello, world!", +} + +if !cmp.Equal(got, want) { + t.Errorf("Blog post = %v, want = %v", got, want) +} +``` + +Для более предметно-ориентированных помощников сравнения предпочитайте +возвращать значение или ошибку, которые можно использовать в сообщении об ошибке +теста, вместо передачи `*testing.T` и вызова его методов сообщения об ошибках: + +```go +// Хорошо: +func postLength(p BlogPost) int { return len(p.Body) } + +func TestBlogPost_VeritableRant(t *testing.T) { + post := BlogPost{Body: "I am Gunnery Sergeant Hartman, your senior drill instructor."} + + if got, want := postLength(post), 60; got != want { + t.Errorf("Length of post = %v, want %v", got, want) + } +} +``` + +**Лучшая практика:** Если бы `postLength` была нетривиальной, было бы разумно +тестировать ее напрямую, независимо от любых тестов, которые ее используют. + +См. также: + +* [Сравнение равенства и разницы (diffs)](#types-of-equality) +* [Печать разниц (diffs)](#print-diffs) +* Подробнее о различии между тестовыми помощниками и помощниками утверждений + см. [лучшие практики](https://neonxp.ru/pages/gostyleguide/google/best-practices/#test-functions) +* Раздел [Go FAQ] о [фреймворках тестирования] и их мнение об их отсутствии + +[полезные сообщения об ошибках]: #useful-test-failures +[`fmt`]: https://golang.org/pkg/fmt/ +[помеча как тестовый помощник]: #mark-test-helpers +[Go FAQ]: https://go.dev/doc/faq +[фреймворках тестирования]: https://go.dev/doc/faq#testing_framework + +<a id="identify-the-function"></a> + +### Идентификация функции + +В большинстве тестов сообщения об ошибках должны включать имя функции, которая +завершилась неудачей, даже если это кажется очевидным из имени тестовой функции. +Конкретно, ваше сообщение об ошибке должно быть `YourFunc(%v) = %v, want %v` +вместо просто `got %v, want %v`. + +<a id="identify-the-input"></a> + +### Идентификация входных данных + +В большинстве тестов сообщения об ошибках должны включать входные данные +функции, если они кратки. Если соответствующие свойства входных данных не +очевидны (например, потому что входные данные большие или непрозрачные), вы +должны называть свои тестовые случаи описанием того, что тестируется, и выводить +это описание как часть вашего сообщения об ошибке. + +<a id="got-before-want"></a> + +### Got перед want + +Вывод тестов должен включать фактическое значение, которое вернула функция, +перед печатью значения, которое ожидалось. Стандартный формат для вывода тестов +это `YourFunc(%v) = %v, want %v`. Там, где вы бы написали "actual" и "expected", +предпочитайте использовать слова "got" и "want" соответственно. + +Для разниц (diffs) направленность менее очевидна, и поэтому важно включить ключ, +чтобы помочь в интерпретации неудачи. См. [раздел о печати разниц]. Независимо +от порядка diff, который вы используете в своих сообщениях об ошибках, вы должны +явно указать его как часть сообщения об ошибке, поскольку существующий код +непоследователен в порядке. + +[раздел о печати разниц]: #print-diffs + +<a id="compare-full-structures"></a> + +### Полное сравнение структур + +Если ваша функция возвращает структуру (или любой тип данных с несколькими +полями, такой как срезы, массивы и карты), избегайте написания тестового кода, +который выполняет ручное поле-за-полем сравнение структуры. Вместо этого +сконструируйте данные, которые вы ожидаете, что ваша функция вернет, и +сравнивайте напрямую с помощью [глубокого сравнения (deep comparison)]. + +**Примечание:** Это не применяется, если ваши данные содержат нерелевантные +поля, которые затемняют намерение теста. + +Если вашу структуру нужно сравнивать на приблизительное (или эквивалентное +семантическое) равенство или она содержит поля, которые не могут быть сравнены +на равенство (например, если одно из полей — `io.Reader`), настройка сравнения +[`cmp.Diff`] или [`cmp.Equal`] с опциями [`cmpopts`], такими как +[`cmpopts.IgnoreInterfaces`], может удовлетворить ваши потребности +([пример](https://play.golang.org/p/vrCUNVfxsvF)). + +Если ваша функция возвращает несколько возвращаемых значений, вам не нужно +оборачивать их в структуру перед сравнением. Просто сравните возвращаемые +значения по отдельности и выведите их. + +```go +// Хорошо: +val, multi, tail, err := strconv.UnquoteChar(`\"Fran & Freddie's Diner\"`, '"') +if err != nil { + t.Fatalf(...) +} +if val != `"` { + t.Errorf(...) +} +if multi { + t.Errorf(...) +} +if tail != `Fran & Freddie's Diner"` { + t.Errorf(...) +} +``` + +[глубокого сравнения (deep comparison)]: #types-of-equality +[`cmpopts`]: https://pkg.go.dev/github.com/google/go-cmp/cmp/cmpopts +[`cmpopts.IgnoreInterfaces`]: + https://pkg.go.dev/github.com/google/go-cmp/cmp/cmpopts#IgnoreInterfaces + +<a id="compare-stable-results"></a> + +### Сравнение стабильных результатов + +Избегайте сравнения результатов, которые могут зависеть от стабильности вывода +пакета, которым вы не владеете. Вместо этого тест должен сравнивать семантически +релевантную информацию, которая стабильна и устойчива к изменениям в +зависимостях. Для функциональности, возвращающей форматированную строку или +сериализованные байты, как правило, небезопасно предполагать, что вывод +стабилен. + +Например, [`json.Marshal`] может измениться (и менялся в прошлом) в конкретных +байтах, которые он выдает. Тесты, выполняющие строковое равенство на JSON +строке, могут сломаться, если пакет `json` изменит способ сериализации байтов. +Вместо этого более надежный тест будет анализировать содержимое JSON строки и +убеждаться, что оно семантически эквивалентно некоторой ожидаемой структуре +данных. + +[`json.Marshal`]: https://golang.org/pkg/encoding/json/#Marshal + +<a id="keep-going"></a> + +### Продолжать выполнение + +Тесты должны продолжать работать как можно дольше, даже после неудачи, чтобы +вывести все неудачные проверки за один запуск. Таким образом, разработчик, +который исправляет падающий тест, не должен перезапускать тест после исправления +каждой ошибки, чтобы найти следующую ошибку. + +Предпочитайте вызов `t.Error` вместо `t.Fatal` для сообщения о несоответствии. +При сравнении нескольких различных свойств вывода функции используйте `t.Error` +для каждого из этих сравнений. + +```go +// Хорошо: +gotMean, gotVariance, err := MyDistribution(input) +if err != nil { + t.Fatalf("MyDistribution(%v) returned unexpected error: %v", input, err) +} +if diff := cmp.Diff(wantMean, gotMean); diff != "" { + t.Errorf("MyDistribution(%v) returned unexpected difference in mean value (-want +got):\n%s", input, diff) +} +if diff := cmp.Diff(wantVariance, gotVariance); diff != "" { + t.Errorf("MyDistribution(%v) returned unexpected difference in variance value (-want +got):\n%s", input, diff) +} +``` + +Вызов `t.Fatal` в первую очередь полезен для сообщения о неожиданном условии +(таком как ошибка или несоответствие вывода), когда последующие неудачи были бы +бессмысленны или даже вводили бы исследователя в заблуждение. Обратите внимание, +как код ниже вызывает `t.Fatalf` и *затем* `t.Errorf`: + +```go +// Хорошо: +gotEncoded := Encode(input) +if gotEncoded != wantEncoded { + t.Fatalf("Encode(%q) = %q, want %q", input, gotEncoded, wantEncoded) + // Не имеет смысла декодировать из неожиданного закодированного ввода. +} +gotDecoded, err := Decode(gotEncoded) +if err != nil { + t.Fatalf("Decode(%q) returned unexpected error: %v", gotEncoded, err) +} +if gotDecoded != input { + t.Errorf("Decode(%q) = %q, want %q", gotEncoded, gotDecoded, input) +} +``` + +Для табличных тестов рассмотрите использование подтестов и используйте `t.Fatal` +вместо `t.Error` и `continue`. См. также [GoTip #25: Subtests: Making Your Tests +Lean](https://google.github.io/styleguide/go/index.html#gotip). + +**Лучшая практика:** Для дальнейшего обсуждения о том, когда следует +использовать `t.Fatal`, см. [лучшие практики](https://neonxp.ru/pages/gostyleguide/google/best-practices/#t-fatal). + +<a id="types-of-equality"></a> + +### Сравнение равенства и разницы (diffs) + +Оператор `==` вычисляет равенство, используя [определенные языком сравнения]. +Скалярные значения (числа, булевы и т.д.) сравниваются на основе их значений, но +только некоторые структуры и интерфейсы можно сравнивать таким образом. +Указатели сравниваются на основе того, указывают ли они на одну и ту же +переменную, а не на основе равенства значений, на которые они указывают. + +Пакет [`cmp`] может сравнивать более сложные структуры данных, не обрабатываемые +адекватно `==`, такие как срезы. Используйте [`cmp.Equal`] для сравнения +равенства и [`cmp.Diff`] для получения читаемой человеком разницы между +объектами. + +```go +// Хорошо: +want := &Doc{ + Type: "blogPost", + Comments: 2, + Body: "This is the post body.", + Authors: []string{"isaac", "albert", "emmy"}, +} +if !cmp.Equal(got, want) { + t.Errorf("AddPost() = %+v, want %+v", got, want) +} +``` + +Как универсальная библиотека сравнения, `cmp` может не знать, как сравнивать +определенные типы. Например, она может сравнивать сообщения protobuf только если +передана опция [`protocmp.Transform`]. + +<!-- The order of want and got here is deliberate. See comment in #print-diffs. --> + +```go +// Хорошо: +if diff := cmp.Diff(want, got, protocmp.Transform()); diff != "" { + t.Errorf("Foo() returned unexpected difference in protobuf messages (-want +got):\n%s", diff) +} +``` + +Хотя пакет `cmp` не является частью стандартной библиотеки Go, он поддерживается +командой Go и должен обеспечивать стабильные результаты равенства с течением +времени. Он настраивается пользователем и должен удовлетворять большинству +потребностей в сравнении. + +[определенные языком сравнения]: http://golang.org/ref/spec#Comparison_operators +[`cmp`]: https://pkg.go.dev/github.com/google/go-cmp/cmp +[`cmp.Equal`]: https://pkg.go.dev/github.com/google/go-cmp/cmp#Equal +[`cmp.Diff`]: https://pkg.go.dev/github.com/google/go-cmp/cmp#Diff +[`protocmp.Transform`]: + https://pkg.go.dev/google.golang.org/protobuf/testing/protocmp#Transform + +Существующий код может использовать следующие более старые библиотеки и может +продолжать использовать их для согласованности: + +* [`pretty`] создает эстетически приятные отчеты о различиях. Однако он + довольно намеренно считает значения, имеющие одинаковое визуальное + представление, равными. В частности, `pretty` не улавливает различия между + nil срезами и пустыми, не чувствителен к разным реализациям интерфейсов с + идентичными полями, и возможно использовать вложенную карту в качестве + основы для сравнения со значением структуры. Он также сериализует все + значение в строку перед созданием diff, и, как таковой, не является хорошим + выбором для сравнения больших значений. По умолчанию он сравнивает + неэкспортируемые поля, что делает его чувствительным к изменениям в деталях + реализации в ваших зависимостях. По этой причине нецелесообразно + использовать `pretty` на сообщениях protobuf. + +[`pretty`]: https://pkg.go.dev/github.com/kylelemons/godebug/pretty + +Предпочитайте использовать `cmp` для нового кода, и стоит рассмотреть обновление +старого кода для использования `cmp`, где и когда это практично. + +Старый код может использовать функцию стандартной библиотеки `reflect.DeepEqual` +для сравнения сложных структур. `reflect.DeepEqual` не следует использовать для +проверки равенства, так как она чувствительна к изменениям в неэкспортированных +полях и другим деталям реализации. Код, использующий `reflect.DeepEqual`, должен +быть обновлен до одной из вышеупомянутых библиотек. + +**Примечание:** Пакет `cmp` предназначен для тестирования, а не для +использования в продакшене. Как таковой, он может вызывать панику, когда +подозревает, что сравнение выполнено неправильно, чтобы дать инструкции +пользователям, как улучшить тест, чтобы он был менее хрупким. Учитывая +склонность cmp к панике, он непригоден для кода, который используется в +продакшене, поскольку ложная паника может быть фатальной. + +<a id="level-of-detail"></a> + +### Уровень детализации + +Обычное сообщение об ошибке, подходящее для большинства тестов Go, это +`YourFunc(%v) = %v, want %v`. Однако бывают случаи, которые могут потребовать +больше или меньше деталей: + +* Тесты, выполняющие сложные взаимодействия, должны также описывать + взаимодействия. Например, если один и тот же `YourFunc` вызывается + несколько раз, идентифицируйте, какой вызов провалил тест. Если важно знать + любое дополнительное состояние системы, включите это в вывод ошибки (или + хотя бы в логи). +* Если данные представляют собой сложную структуру со значительным шаблонным + кодом, допустимо описать только важные части в сообщении, но не чрезмерно + затемняйте данные. +* Ошибки настройки не требуют такого же уровня детализации. Если тестовый + помощник заполняет таблицу Spanner, но Spanner был выключен, вам, вероятно, + не нужно включать, какие тестовые входные данные вы собирались сохранить в + базе данных. `t.Fatalf("Setup: Failed to set up test database: %s", err)` + обычно достаточно полезно, чтобы решить проблему. + +**Совет:** Заставьте ваш режим отказа срабатывать во время разработки. +Просмотрите, как выглядит сообщение об ошибке, и может ли сопровождающий +эффективно справиться с неудачей. + +Существуют некоторые методы для ясного воспроизведения тестовых входов и +выходов: + +* При выводе строковых данных [`%q` часто полезен](#use-percent-q) для + выделения важности значения и более легкого обнаружения плохих значений. +* При выводе (маленьких) структур `%+v` может быть полезнее, чем `%v`. +* Когда проверка больших значений завершается неудачей, [печать разницы + (diff)](#print-diffs) может облегчить понимание неудачи. + +<a id="print-diffs"></a> + +### Печать разниц (diffs) + +Если ваша функция возвращает большой вывод, читающему может быть трудно найти +различия, когда ваш тест проваливается. Вместо печати и возвращенного значения, +и ожидаемого значения создайте diff. + +Для вычисления разниц для таких значений предпочтительна `cmp.Diff`, особенно +для новых тестов и нового кода, но могут использоваться и другие инструменты. +См. [типы равенства] для рекомендаций относительно сильных и слабых сторон +каждой функции. + +* [`cmp.Diff`] + +* [`pretty.Compare`] + +Вы можете использовать пакет [`diff`] для сравнения многострочных строк или +списков строк. Вы можете использовать это как строительный блок для других видов +разниц. + +[типы равенства]: #types-of-equality +[`diff`]: https://pkg.go.dev/github.com/kylelemons/godebug/diff +[`pretty.Compare`]: + https://pkg.go.dev/github.com/kylelemons/godebug/pretty#Compare + +Добавьте некоторый текст в ваше сообщение об ошибке, объясняющий направление +diff. + +<!-- +The reversed order of want and got in these examples is intentional, as this is +the prevailing order across the Google codebase. The lack of a stance on which +order to use is also intentional, as there is no consensus which is +"most readable." + + +--> + +* Что-то вроде `diff (-want +got)` хорошо, когда вы используете пакеты `cmp`, + `pretty` и `diff` (если вы передаете `(want, got)` в функцию), потому что + `-` и `+`, которые вы добавляете в строку формата, будут соответствовать `-` + и `+`, которые фактически появляются в начале строк diff. Если вы передаете + `(got, want)` в вашу функцию, правильным ключом будет `(-got +want)` вместо + этого. + +* Пакет `messagediff` использует другой формат вывода, поэтому сообщение `diff + (want -> got)` уместно, когда вы его используете (если вы передаете `(want, + got)` в функцию), потому что направление стрелки будет соответствовать + направлению стрелки в строках "modified". + +Diff будет занимать несколько строк, поэтому вы должны напечатать новую строку +перед печатью diff. + +<a id="test-error-semantics"></a> + +### Тестирование семантики ошибок + +Когда модульный тест выполняет строковые сравнения или использует обычный `cmp` +для проверки того, что возвращаются определенные типы ошибок для определенных +входных данных, вы можете обнаружить, что ваши тесты становятся хрупкими, если +какое-либо из этих сообщений об ошибках будет переформулировано в будущем. +Поскольку это может превратить ваш модульный тест в детектор изменений (см. +[TotT: Change-Detector Tests Considered Harmful][tott-350] ), не используйте +строковое сравнение для проверки того, какой тип ошибки возвращает ваша функция. +Однако допустимо использовать строковые сравнения для проверки того, что +сообщения об ошибках, исходящие из тестируемого пакета, удовлетворяют +определенным свойствам, например, что оно включает имя параметра. + +Значения ошибок в Go обычно имеют компонент, предназначенный для человеческого +восприятия, и компонент, предназначенный для семантического управления потоком. +Тесты должны стремиться тестировать только семантическую информацию, которую +можно надежно наблюдать, а не отображаемую информацию, предназначенную для +отладки человеком, поскольку последняя часто подвержена будущим изменениям. +Рекомендации по созданию ошибок со смысловым значением см. [лучшие практики +относительно ошибок](https://neonxp.ru/pages/gostyleguide/google/best-practices/#error-handling). Если ошибка с недостаточной +семантической информацией исходит из зависимости вне вашего контроля, +рассмотрите возможность создания отчета об ошибке (bug) владельцу, чтобы помочь +улучшить API, а не полагаться на разбор сообщения об ошибке. + +В рамках модульных тестов часто важно только то, произошла ли ошибка или нет. +Если да, то достаточно проверить только, была ли ошибка ненулевой, когда вы +ожидали ошибки. Если вы хотите проверить, что ошибка семантически соответствует +какой-то другой ошибке, рассмотрите использование [`errors.Is`] или `cmp` с +[`cmpopts.EquateErrors`]. + +> **Примечание:** Если тест использует [`cmpopts.EquateErrors`], но все его +> значения `wantErr` либо `nil`, либо `cmpopts.AnyError`, то использование `cmp` +> является [ненужным механизмом](https://neonxp.ru/pages/gostyleguide/google/guide/#least-mechanism). Упростите код, сделав +> поле `want` типа `bool`. Затем вы можете использовать простое сравнение с +> `!=`. +> +> ```go +> // Хорошо: +> err := f(test.input) +> if gotErr := err != nil; gotErr != test.wantErr { +> t.Errorf("f(%q) = %v, want error presence = %v", test.input, err, test.wantErr) +> } +> ``` + +См. также [GoTip #13: Designing Errors for +Checking](https://google.github.io/styleguide/go/index.html#gotip). + +[tott-350]: + https://testing.googleblog.com/2015/01/testing-on-toilet-change-detector-tests.html +[`cmpopts.EquateErrors`]: + https://pkg.go.dev/github.com/google/go-cmp/cmp/cmpopts#EquateErrors +[`errors.Is`]: https://pkg.go.dev/errors#Is + +<a id="test-structure"></a> + +## Структура тестов + +<a id="subtests"></a> + +### Подтесты (Subtests) + +Стандартная библиотека тестирования Go предоставляет возможность [определять +подтесты]. Это позволяет гибкость в настройке и очистке, управлении +параллелизмом и фильтрации тестов. Подтесты могут быть полезны (особенно для +табличных тестов), но их использование не обязательно. См. также [пост в блоге +Go о подтестах](https://blog.golang.org/subtests). + +Подтесты не должны зависеть от выполнения других случаев для успеха или +начального состояния, поскольку ожидается, что подтесты могут быть запущены +индивидуально с использованием флагов `go test -run` или выражений [фильтра +тестов] Bazel. + +[определять подтесты]: + https://pkg.go.dev/testing#hdr-Subtests_and_Sub_benchmarks +[фильтра тестов]: https://bazel.build/docs/user-manual#test-filter + +<a id="subtest-names"></a> + +#### Имена подтестов + +Назовите ваш подтест так, чтобы он был читаем в выводе теста и полезен в +командной строке для пользователей фильтрации тестов. Когда вы используете +`t.Run` для создания подтеста, первый аргумент используется как описательное имя +для теста. Чтобы гарантировать, что результаты тестов читаемы для людей, +читающих логи, выбирайте имена подтестов, которые останутся полезными и +читаемыми после экранирования. Думайте об именах подтестов скорее как об +идентификаторе функции, чем о прозаическом описании. + +Тестовый раннер заменяет пробелы подчеркиваниями и экранирует непечатаемые +символы. Чтобы обеспечить точную корреляцию между логами тестов и исходным +кодом, рекомендуется избегать использования этих символов в именах подтестов. + +Если ваши тестовые данные выигрывают от более длинного описания, рассмотрите +возможность поместить описание в отдельное поле (возможно, для печати с помощью +`t.Log` или рядом с сообщениями об ошибках). + +Подтесты могут быть запущены индивидуально с использованием флагов [Go test +runner] или Bazel [фильтра тестов], поэтому выбирайте описательные имена, +которые также легко набирать. + +> **Предупреждение:** Символы слеша особенно недружелюбны в именах подтестов, +> поскольку они имеют [особое значение для фильтров тестов]. +> +> > ```sh +> > # Плохо: +> > # Предполагая TestTime и t.Run("America/New_York", ...) +> > bazel test :mytest --test_filter="Time/New_York" # Ничего не запускает! +> > bazel test :mytest --test_filter="Time//New_York" # Правильно, но неудобно. +> > ``` + +Чтобы [идентифицировать входные данные] функции, включите их в сообщения об +ошибках теста, где они не будут экранированы тестовым раннером. + +```go +// Хорошо: +func TestTranslate(t *testing.T) { + data := []struct { + name, desc, srcLang, dstLang, srcText, wantDstText string + }{ + { + name: "hu=en_bug-1234", + desc: "regression test following bug 1234. contact: cleese", + srcLang: "hu", + srcText: "cigarettát és egy öngyújtót kérek", + dstLang: "en", + wantDstText: "cigarettes and a lighter please", + }, // ... + } + for _, d := range data { + t.Run(d.name, func(t *testing.T) { + got := Translate(d.srcLang, d.dstLang, d.srcText) + if got != d.wantDstText { + t.Errorf("%s\nTranslate(%q, %q, %q) = %q, want %q", + d.desc, d.srcLang, d.dstLang, d.srcText, got, d.wantDstText) + } + }) + } +} +``` + +Вот несколько примеров того, чего следует избегать: + +```go +// Плохо: +// Слишком многословно. +t.Run("check that there is no mention of scratched records or hovercrafts", ...) +// Слеши вызывают проблемы в командной строке. +t.Run("AM/PM confusion", ...) +``` + +См. также [Go Tip #117: Subtest +Names](https://google.github.io/styleguide/go/index.html#gotip). + +[Go test runner]: https://golang.org/cmd/go/#hdr-Testing_flags +[идентифицировать входные данные]: #identify-the-input +[особое значение для фильтров тестов]: + https://blog.golang.org/subtests#:~:text=Perhaps%20a%20bit,match%20any%20tests + +<a id="table-driven-tests"></a> + +### Табличные тесты + +Используйте табличные тесты, когда множество различных тестовых случаев могут +быть протестированы с помощью сходной тестовой логики. + +* При тестировании того, равен ли фактический вывод функции ожидаемому выводу. + Например, множество [тестов `fmt.Sprintf`] или минимальный фрагмент ниже. +* При тестировании того, соответствуют ли выводы функции всегда одному и тому + же набору инвариантов. Например, [тесты для `net.Dial`]. + +[тестов `fmt.Sprintf`]: + https://cs.opensource.google/go/go/+/master:src/fmt/fmt_test.go +[тестов для `net.Dial`]: + https://cs.opensource.google/go/go/+/master:src/net/dial_test.go;l=318;drc=5b606a9d2b7649532fe25794fa6b99bd24e7697c + +Вот минимальная структура табличного теста. При необходимости вы можете +использовать другие имена или добавить дополнительные средства, такие как +подтесты или функции настройки и очистки. Всегда помните о [полезных сообщениях +об ошибках тестов](#useful-test-failures). + +```go +// Хорошо: +func TestCompare(t *testing.T) { + compareTests := []struct { + a, b string + want int + }{ + {"", "", 0}, + {"a", "", 1}, + {"", "a", -1}, + {"abc", "abc", 0}, + {"ab", "abc", -1}, + {"abc", "ab", 1}, + {"x", "ab", 1}, + {"ab", "x", -1}, + {"x", "a", 1}, + {"b", "x", -1}, + // тестирование chunked-реализации runtime·memeq + {"abcdefgh", "abcdefgh", 0}, + {"abcdefghi", "abcdefghi", 0}, + {"abcdefghi", "abcdefghj", -1}, + } + + for _, test := range compareTests { + got := Compare(test.a, test.b) + if got != test.want { + t.Errorf("Compare(%q, %q) = %v, want %v", test.a, test.b, got, test.want) + } + } +} +``` + +**Примечание**: Сообщения об ошибках в приведенном выше примере соответствуют +рекомендациям [идентифицировать функцию](#identify-the-function) и +[идентифицировать входные данные](#identify-the-input). Нет необходимости +[идентифицировать строку численно](#table-tests-identifying-the-row). + +Когда некоторые тестовые случаи нужно проверять с помощью логики, отличной от +других тестовых случаев, уместно написать несколько тестовых функций, как +объясняется в [GoTip #50: Disjoint Table Tests]. + +Когда дополнительные тестовые случаи просты (например, базовая проверка ошибок) +и не вводят условный поток кода в теле цикла табличного теста, допустимо +включить этот случай в существующий тест, хотя будьте осторожны, используя такую +логику. То, что начинается просто сегодня, может органически вырасти во что-то +неподдерживаемое. + +Например: + +```go +func TestDivide(t *testing.T) { + tests := []struct { + dividend, divisor int + want int + wantErr bool + }{ + { + dividend: 4, + divisor: 2, + want: 2, + }, + { + dividend: 10, + divisor: 2, + want: 5, + }, + { + dividend: 1, + divisor: 0, + wantErr: true, + }, + } + + for _, test := range tests { + got, err := Divide(test.dividend, test.divisor) + if (err != nil) != test.wantErr { + t.Errorf("Divide(%d, %d) error = %v, want error presence = %t", test.dividend, test.divisor, err, test.wantErr) + } + + // В этом примере мы тестируем значение результата только когда тестируемая функция не завершилась неудачей. + if err != nil { + continue + } + + if got != test.want { + t.Errorf("Divide(%d, %d) = %d, want %d", test.dividend, test.divisor, got, test.want) + } + } +} +``` + +Более сложная логика в вашем тестовом коде, например сложная проверка ошибок на +основе условных различий в настройке теста (часто основанных на входных +параметрах табличного теста), может быть [трудной для +понимания](https://neonxp.ru/pages/gostyleguide/google/guide/#maintainability), когда каждая запись в таблице имеет +специализированную логику на основе входных данных. Если тестовые случаи имеют +разную логику, но идентичную настройку, последовательность +[подтестов](#subtests) внутри одной тестовой функции может быть более читаемой. +Тестовый помощник также может быть полезен для упрощения настройки теста с целью +сохранения читаемости тела теста. + +Вы можете комбинировать табличные тесты с несколькими тестовыми функциями. +Например, при тестировании того, что вывод функции точно соответствует +ожидаемому выводу и что функция возвращает ненулевую ошибку для неверного ввода, +лучшим подходом является написание двух отдельных табличных тестовых функций: +одну для обычных не-ошибочных выводов, и одну для ошибочных выводов. + +[GoTip #50: Disjoint Table Tests]: + https://google.github.io/styleguide/go/index.html#gotip + +<a id="table-tests-data-driven"></a> + +#### Тестовые случаи на основе данных + +Строки табличных тестов иногда могут становиться сложными, причем значения строк +диктуют условное поведение внутри тестового случая. Дополнительная ясность от +дублирования между тестовыми случаями необходима для читаемости. + +```go +// Хорошо: +type decodeCase struct { + name string + input string + output string + err error +} + +func TestDecode(t *testing.T) { + // setupCodex медленный, так как создает реальный Codex для теста. + codex := setupCodex(t) + + var tests []decodeCase // строки опущены для краткости + + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + output, err := Decode(test.input, codex) + if got, want := output, test.output; got != want { + t.Errorf("Decode(%q) = %v, want %v", test.input, got, want) + } + if got, want := err, test.err; !cmp.Equal(got, want) { + t.Errorf("Decode(%q) err %q, want %q", test.input, got, want) + } + }) + } +} + +func TestDecodeWithFake(t *testing.T) { + // fakeCodex — это быстрое приближение реального Codex. + codex := newFakeCodex() + + var tests []decodeCase // строки опущены для краткости + + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + output, err := Decode(test.input, codex) + if got, want := output, test.output; got != want { + t.Errorf("Decode(%q) = %v, want %v", test.input, got, want) + } + if got, want := err, test.err; !cmp.Equal(got, want) { + t.Errorf("Decode(%q) err %q, want %q", test.input, got, want) + } + }) + } +} +``` + +В контринте ниже обратите внимание, как сложно различить, какой тип `Codex` +используется на тестовый случай в настройке случая. (Выделенные части нарушают +совет из [TotT: Data Driven Traps!][tott-97] .) + +```go +// Плохо: +type decodeCase struct { + name string + input string + codex testCodex + output string + err error +} + +type testCodex int + +const ( + fake testCodex = iota + prod +) + +func TestDecode(t *testing.T) { + var tests []decodeCase // строки опущены для краткости + + for _, test := tests { + t.Run(test.name, func(t *testing.T) { + var codex Codex + switch test.codex { + case fake: + codex = newFakeCodex() + case prod: + codex = setupCodex(t) + default: + t.Fatalf("Unknown codex type: %v", codex) + } + output, err := Decode(test.input, codex) + if got, want := output, test.output; got != want { + t.Errorf("Decode(%q) = %q, want %q", test.input, got, want) + } + if got, want := err, test.err; !cmp.Equal(got, want) { + t.Errorf("Decode(%q) err %q, want %q", test.input, got, want) + } + }) + } +} +``` + +[tott-97]: https://testing.googleblog.com/2008/09/tott-data-driven-traps.html + +<a id="table-tests-identifying-the-row"></a> + +#### Идентификация строки + +Не используйте индекс теста в тестовой таблице в качестве замены именования +ваших тестов или печати входных данных. Никто не хочет проходить через вашу +тестовую таблицу и считать записи, чтобы выяснить, какой тестовый случай +провалился. + +```go +// Плохо: +tests := []struct { + input, want string +}{ + {"hello", "HELLO"}, + {"wORld", "WORLD"}, +} +for i, d := range tests { + if strings.ToUpper(d.input) != d.want { + t.Errorf("Failed on case #%d", i) + } +} +``` + +Добавьте описание теста в вашу тестовую структуру и печатайте его вместе с +сообщениями об ошибках. При использовании подтестов имя вашего подтеста должно +эффективно идентифицировать строку. + +**Важно:** Хотя `t.Run` ограничивает область вывода и выполнения, вы должны +всегда [идентифицировать входные данные]. Имена строк табличных тестов должны +следовать [руководству по именованию подтестов]. + +[идентифицировать входные данные]: #identify-the-input +[руководству по именованию подтестов]: #subtest-names + +<a id="mark-test-helpers"></a> + +### Тестовые помощники (Test helpers) + +Тестовый помощник — это функция, выполняющая задачу настройки или очистки. Все +ошибки, возникающие в тестовых помощниках, должны быть ошибками окружения (а не +кода под тестом) — например, когда тестовая база данных не может быть запущена +потому что на этой машине не осталось свободных портов. + +Если вы передаете `*testing.T`, вызовите [`t.Helper`], чтобы приписать ошибки в +тестовом помощнике строке, где помощник вызывается. Этот параметр должен идти +после параметра [контекста](#contexts), если он присутствует, и перед любыми +оставшимися параметрами. + +```go +// Хорошо: +func TestSomeFunction(t *testing.T) { + golden := readFile(t, "testdata/golden-result.txt") + // ... тесты против golden ... +} + +// readFile возвращает содержимое файла данных. +// Может вызываться только из той же горутины, которая начала тест. +func readFile(t *testing.T, filename string) string { + t.Helper() + contents, err := runfiles.ReadFile(filename) + if err != nil { + t.Fatal(err) + } + return string(contents) +} +``` + +Не используйте этот шаблон, когда он скрывает связь между неудачей теста и +условиями, которые к ней привели. Конкретно, рекомендации о [библиотеках +утверждений](#assert) все еще применяются, и [`t.Helper`] не должен +использоваться для реализации таких библиотек. + +**Совет:** Подробнее о различии между тестовыми помощниками и помощниками +утверждений см. [лучшие практики](https://neonxp.ru/pages/gostyleguide/google/best-practices/#test-functions). + +Хотя вышесказанное относится к `*testing.T`, большая часть рекомендаций остается +той же для вспомогательных функций бенчмарков и фаззинга. + +[`t.Helper`]: https://pkg.go.dev/testing#T.Helper + +<a id="test-package"></a> + +### Тестовый пакет + +<a id="TOC-TestPackage"></a> + +<a id="test-same-package"></a> + +#### Тесты в том же пакете + +Тесты могут быть определены в том же пакете, что и тестируемый код. + +Чтобы написать тест в том же пакете: + +* Поместите тесты в файл `foo_test.go` +* Используйте `package foo` для тестового файла +* Не импортируйте явно тестируемый пакет + +```build +# Хорошо: +go_library( + name = "foo", + srcs = ["foo.go"], + deps = [ + ... + ], +) + +go_test( + name = "foo_test", + size = "small", + srcs = ["foo_test.go"], + library = ":foo", + deps = [ + ... + ], +) +``` + +Тест в том же пакете может обращаться к неэкспортированным идентификаторам в +пакете. Это может обеспечить лучшее покрытие тестами и более лаконичные тесты. +Имейте в виду, что любые [примеры], объявленные в тесте, не будут иметь имен +пакетов, которые понадобятся пользователю в их коде. + +[`library`]: + https://github.com/bazelbuild/rules_go/blob/master/docs/go/core/rules.md#go_library +[примеры]: #examples + +<a id="test-different-package"></a> + +#### Тесты в другом пакете + +Не всегда уместно или даже возможно определить тест в том же пакете, что и +тестируемый код. В этих случаях используйте имя пакета с суффиксом `_test`. Это +исключение из правила "без подчеркиваний" для [имен пакетов](#package-names). +Например: + +* Если интеграционный тест не имеет очевидной библиотеки, к которой он + принадлежит + + ```go + // Хорошо: + package gmailintegration_test + + import "testing" + ``` + +* Если определение тестов в том же пакете приводит к циклическим зависимостям + + ```go + // Хорошо: + package fireworks_test + + import ( + "fireworks" + "fireworkstestutil" // fireworkstestutil также импортирует fireworks + ) + ``` + +<a id="use-package-testing"></a> + +### Использование пакета `testing` + +Стандартная библиотека Go предоставляет пакет [`testing`]. Это единственный +фреймворк тестирования, разрешенный для кода Go в кодовой базе Google. В +частности, [библиотеки утверждений](#assert) и сторонние фреймворки тестирования +не разрешены. + +Пакет `testing` предоставляет минимальный, но полный набор функциональности для +написания хороших тестов: + +* Тесты верхнего уровня +* Бенчмарки +* [Исполняемые примеры](https://blog.golang.org/examples) +* Подтесты +* Логирование +* Ошибки и фатальные ошибки + +Они разработаны для слаженной работы с основными языковыми возможностями, такими +как [составные литералы] и [if с инициализатором], чтобы позволить авторам +тестов писать [понятные, читаемые и поддерживаемые тесты]. + +[`testing` package]: https://pkg.go.dev/testing +[составные литералы]: https://go.dev/ref/spec#Composite_literals +[if с инициализатором]: https://go.dev/ref/spec#If_statements + +<a id="non-decisions"></a> + +## Не-решения + +Руководство по стилю не может перечислять позитивные предписания по всем +вопросам, как не может оно перечислить все вопросы, по которым оно не дает +мнения. Тем не менее, вот несколько вещей, по которым сообщество читаемости +ранее спорило и не достигло консенсуса. + +* **Локальная инициализация переменных нулевым значением**. `var i int` и `i + := 0` эквивалентны. См. также [лучшие практики инициализации]. +* **Пустой составной литерал vs. `new` или `make`**. `&File{}` и `new(File)` + эквивалентны. Так же `map[string]bool{}` и `make(map[string]bool)`. См. + также [лучшие практики составных объявлений]. +* **Порядок аргументов got, want в вызовах cmp.Diff**. Будьте локально + последовательны и [включите легенду](#print-diffs) в ваше сообщение об + ошибке. +* **`errors.New` vs `fmt.Errorf` на неформатированных строках**. + `errors.New("foo")` и `fmt.Errorf("foo")` могут использоваться + взаимозаменяемо. + +Если возникнут особые обстоятельства, наставник по читаемости может сделать +необязательный комментарий, но в целом автор волен выбирать предпочитаемый им +стиль в данной ситуации. + +Естественно, если что-то, не охваченное руководством по стилю, требует +дополнительного обсуждения, авторы могут спросить — либо в конкретном ревью, +либо на внутренних досках сообщений. + +[лучшие практики составных объявлений]: + https://google.github.io/styleguide/go/best-practices#vardeclcomposite +[лучшие практики инициализации]: + https://google.github.io/styleguide/go/best-practices#vardeclinitialization diff --git a/content/pages/gostyleguide/google/guide.md b/content/pages/gostyleguide/google/guide.md new file mode 100644 index 0000000..31b3b33 --- /dev/null +++ b/content/pages/gostyleguide/google/guide.md @@ -0,0 +1,495 @@ +--- +order: 3 +title: Google Go Style Guide — Руководство +--- + +# Руководство по стилю Go (Go Style Guide) + +Оригинал: https://google.github.io/styleguide/go/guide + +[Обзор](https://neonxp.ru/pages/gostyleguide/google/) | [Руководство](https://neonxp.ru/pages/gostyleguide/google/guide) | [Решения](https://neonxp.ru/pages/gostyleguide/google/decisions) | +[Лучшие практики](https://neonxp.ru/pages/gostyleguide/google/best-practices) + + +**Примечание:** Это часть серии документов, описывающих [Стиль Go (Go +Style)](https://neonxp.ru/pages/gostyleguide/google/) в Google. Данный документ является **[нормативным +(normative)](https://neonxp.ru/pages/gostyleguide/google/#normative) и [каноническим (canonical)](https://neonxp.ru/pages/gostyleguide/google/#canonical)**. +Подробнее см. [в обзоре](https://neonxp.ru/pages/gostyleguide/google/#about). + +<a id="principles"></a> + +## Принципы стиля + +Существует несколько основополагающих принципов, которые суммируют подход к +написанию читаемого кода на Go. Ниже перечислены атрибуты читаемого кода в +порядке важности: + +1. **[Понятность (Clarity)]**: Цель и обоснование кода ясны читателю. +1. **[Простота (Simplicity)]**: Код достигает своей цели наиболее простым + способом. +1. **[Лаконичность (Concision)]**: Код имеет высокое отношение сигнала к шуму. +1. **[Поддерживаемость (Maintainability)]**: Код написан так, чтобы его было + легко поддерживать. +1. **[Согласованность (Consistency)]**: Код согласуется с более широкой + кодобазой Google. + +[Понятность (Clarity)]: #clarity +[Простота (Simplicity)]: #simplicity +[Лаконичность (Concision)]: #concision +[Поддерживаемость (Maintainability)]: #maintainability +[Согласованность (Consistency)]: #consistency + +<a id="clarity"></a> + +### Понятность (Clarity) + +Основная цель удобочитаемости — создание кода, который понятен читателю. + +Понятность достигается в первую очередь за счет эффективного именования, +полезных комментариев и продуманной организации кода. + +Понятность следует рассматривать с точки зрения читателя, а не автора кода. +Важнее, чтобы код был легок для чтения, а не для написания. Понятность кода +имеет два аспекта: + +* [Что именно делает код?](#clarity-purpose) +* [Почему код делает то, что он делает?](#clarity-rationale) + +<a id="clarity-purpose"></a> + +#### Что именно делает код? + +Go разработан таким образом, чтобы относительно легко было понять, что делает +код. В случаях неопределенности или когда читателю могут потребоваться +предварительные знания для понимания кода, стоит потратить время, чтобы сделать +цель кода более ясной для будущих читателей. Например, может помочь: + +* Использование более описательных имен переменных +* Добавление дополнительных комментариев +* Разделение кода пробелами и комментариями +* Рефакторинг кода в отдельные функции/методы для повышения модульности + +Здесь нет универсального решения, но при разработке кода на Go важно отдавать +приоритет понятности. + +<a id="clarity-rationale"></a> + +#### Почему код делает то, что он делает? + +Обоснование кода часто достаточно ясно передается именами переменных, функций, +методов или пакетов. Если это не так, важно добавить комментарии. "Почему?" +особенно важно, когда код содержит нюансы, с которыми читатель может быть не +знаком, например: + +* Нюанс языка, например, замыкание захватит переменную цикла, но само + замыкание находится далеко от него +* Нюанс бизнес-логики, например, проверка прав доступа, которая должна + различать реального пользователя и того, кто выдает себя за пользователя + +API может требовать осторожного использования. Например, фрагмент кода может +быть сложным и трудным для понимания из-за соображений производительности, или +сложная последовательность математических операций может использовать +преобразования типов неожиданным образом. В этих и многих других случаях важно, +чтобы сопровождающие комментарии и документация объясняли эти аспекты, чтобы +будущие сопровождающие не допустили ошибку и чтобы читатели могли понять код без +необходимости его обратной разработки. + +Также важно осознавать, что некоторые попытки повысить понятность (например, +добавление лишних комментариев) могут фактически затуманить цель кода, добавляя +беспорядок, пересказывая то, что код уже говорит, противореча коду или добавляя +нагрузку по поддержке актуальности комментариев. Позвольте коду говорить самому +за себя (например, делая имена символов самодокументированными), а не добавляйте +избыточные комментарии. Зачастую лучше, чтобы комментарии объясняли, *почему* +что-то сделано, а не *что* делает код. + +Кодовая база Google в значительной степени единообразна и согласована. Часто +бывает, что код, который выделяется (например, использованием незнакомого +шаблона), делает это по уважительной причине, обычно для производительности. +Поддержание этого свойства важно, чтобы дать читателям понять, куда им следует +направить внимание при чтении нового фрагмента кода. + +Стандартная библиотека содержит множество примеров реализации этого принципа. +Среди них: + +* Комментарии сопровождающих в [`package + sort`](https://cs.opensource.google/go/go/+/refs/tags/go1.19.2:src/sort/sort.go). +* Хорошие [запускаемые примеры в том же + пакете](https://cs.opensource.google/go/go/+/refs/tags/go1.19.2:src/sort/example_search_test.go), + которые полезны как пользователям (они [отображаются в + godoc](https://pkg.go.dev/sort#pkg-examples)), так и сопровождающим (они + [запускаются как часть тестов](https://neonxp.ru/pages/gostyleguide/google/decisions/#examples)). +* [`strings.Cut`](https://pkg.go.dev/strings#Cut) — это всего четыре строки + кода, но они повышают [понятность и корректность мест вызова + (callsites)](https://github.com/golang/go/issues/46336). + +<a id="simplicity"></a> + +### Простота (Simplicity) + +Ваш код на Go должен быть простым для тех, кто его использует, читает и +поддерживает. + +Код на Go должен быть написан наиболее простым способом, достигающим его целей, +как с точки зрения поведения, так и производительности. Внутри кодовой базы Go в +Google простой код: + +* Легко читается сверху вниз +* Не предполагает, что вы уже знаете, что он делает +* Не предполагает, что вы можете запомнить весь предшествующий код +* Не имеет ненужных уровней абстракции +* Не имеет имен, которые привлекают внимание к чему-то обыденному +* Делает передачу значений и принятие решений понятными для читателя +* Имеет комментарии, которые объясняют *почему*, а не *что* делает код, чтобы + избежать будущих отклонений +* Имеет самодостаточную документацию +* Имеет полезные ошибки и полезные сообщения об ошибках в тестах +* Часто может быть взаимоисключающим с "умным" кодом + +Могут возникать компромиссы между простотой кода и простотой использования API. +Например, может иметь смысл сделать код более сложным, чтобы конечному +пользователю API было легче правильно его вызывать. И наоборот, также может быть +целесообразно оставить немного дополнительной работы конечному пользователю API, +чтобы код оставался простым и легким для понимания. + +Когда коду требуется сложность, она должна добавляться обдуманно. Обычно это +необходимо, если требуется дополнительная производительность или если у +конкретной библиотеки или сервиса есть несколько различных клиентов. Сложность +может быть оправдана, но она должна сопровождаться документацией, чтобы клиенты +и будущие сопровождающие могли понять и ориентироваться в ней. Это должно +дополняться тестами и примерами, демонстрирующими ее правильное использование, +особенно если существует как "простой", так и "сложный" способ использования +кода. + +Этот принцип не означает, что сложный код нельзя или не следует писать на Go, +или что коду на Go не разрешено быть сложным. Мы стремимся к кодовой базе, +которая избегает ненужной сложности, чтобы, когда сложность появляется, это +указывало на то, что рассматриваемый код требует внимания для понимания и +поддержки. В идеале должны быть сопроводительные комментарии, объясняющие +обоснование и указывающие на меры предосторожности. Это часто возникает при +оптимизации кода для производительности; это часто требует более сложного +подхода, например, предварительного выделения буфера и его повторного +использования в течение времени жизни горутины. Когда сопровождающий видит это, +это должно быть сигналом, что рассматриваемый код критичен для +производительности, и это должно влиять на осторожность при внесении будущих +изменений. С другой стороны, если эта сложность применена без необходимости, она +становится обузой для тех, кому нужно читать или изменять код в будущем. + +Если код оказывается очень сложным, в то время как его цель должна быть простой, +это часто сигнал пересмотреть реализацию, чтобы увидеть, есть ли более простой +способ достичь того же. + +<a id="least-mechanism"></a> + +#### Наименьшая механизация (Least mechanism) + +Если есть несколько способов выразить одну и ту же идею, предпочтите тот, +который использует наиболее стандартные инструменты. Сложные механизмы часто +существуют, но не должны применяться без причины. Легко добавить сложность в код +по мере необходимости, тогда как гораздо сложнее удалить существующую сложность +после того, как выяснилось, что она не нужна. + +1. Стремитесь использовать базовую конструкцию языка (например, канал, срез + (slice), мапу (map), цикл или структуру (struct)), если этого достаточно для + вашего случая использования. +2. Если такой нет, ищите инструмент в стандартной библиотеке (например, + HTTP-клиент или механизм шаблонов (template engine)). +3. Наконец, рассмотрите, есть ли в кодовой базе Google основная библиотека, + которой достаточно, прежде чем вводить новую зависимость или создавать свою + собственную. + +В качестве примера рассмотрим production-код, содержащий флаг, привязанный к +переменной со значением по умолчанию, которое должно быть переопределено в +тестах. Если не предполагается тестирование самого интерфейса командной строки +программы (скажем, с помощью `os/exec`), проще и поэтому предпочтительнее +переопределить привязанное значение напрямую, а не с помощью `flag.Set`. + +Аналогично, если фрагменту кода требуется проверка принадлежности к множеству +(set membership check), часто достаточно мапы с булевыми значениями (например, +`map[string]bool`). Библиотеки, предоставляющие типы и функциональность, похожие +на множества (set), следует использовать только в том случае, если требуются +более сложные операции, которые невозможны или чрезмерно сложны с мапой. + +<a id="concision"></a> + +### Лаконичность (Concision) + +Лаконичный код на Go имеет высокое отношение сигнала к шуму. Легко различить +соответствующие детали, а именование и структура направляют читателя через эти +детали. + +Многое может помешать выделению наиболее важных деталей в любой момент: + +* Повторяющийся код +* Лишний синтаксис +* [Непонятные имена](#naming) +* Ненужная абстракция +* Пробелы + +Повторяющийся код особенно затмевает различия между каждым почти идентичным +разделом и требует от читателя визуального сравнения похожих строк кода, чтобы +найти изменения. [Табличное тестирование (Table-driven testing)] — хороший +пример механизма, который может лаконично вынести общий код за рамки важных +деталей каждого повторения, но выбор того, какие части включить в таблицу, +повлияет на то, насколько легко таблицу понять. + +При рассмотрении нескольких способов структурирования кода стоит подумать, какой +способ делает важные детали наиболее очевидными. + +Понимание и использование общих конструкций кода и идиом также важны для +поддержания высокого отношения сигнала к шуму. Например, следующий блок кода +очень распространен при [обработке ошибок (error handling)], и читатель может +быстро понять его назначение. + +```go +// Хорошо: +if err := doSomething(); err != nil { + // ... +} +``` + +Если код выглядит очень похоже, но имеет тонкое отличие, читатель может не +заметить изменение. В таких случаях стоит намеренно ["усилить" сигнал] проверки +ошибки, добавив комментарий, чтобы привлечь к нему внимание. + +```go +// Хорошо: +if err := doSomething(); err == nil { // если ошибки НЕТ + // ... +} +``` + +[Табличное тестирование (Table-driven testing)]: + https://github.com/golang/go/wiki/TableDrivenTests +[обработке ошибок (error handling)]: https://go.dev/blog/errors-are-values +["усилить" сигнал]: best-practices#signal-boost + +<a id="maintainability"></a> + +### Поддерживаемость (Maintainability) + +Код редактируется гораздо чаще, чем пишется. Читаемый код не только понятен +читателю, который пытается понять, как он работает, но и программисту, которому +нужно его изменить. Ключевое значение имеет понятность. + +Поддерживаемый код: + +* Легко модифицируется будущим программистом правильно +* Имеет API, структурированные таким образом, что они могут элегантно + развиваться +* Четко указывает предположения, которые он делает, и выбирает абстракции, + которые соответствуют структуре проблемы, а не структуре кода +* Избегает ненужной связности и не включает неиспользуемые функции +* Имеет комплексный набор тестов, чтобы гарантировать сохранение заявленного + поведения и корректность важной логики, а тесты предоставляют четкие, + действенные диагностические сообщения в случае неудачи + +При использовании абстракций, таких как интерфейсы и типы, которые по +определению удаляют информацию из контекста, в котором они используются, важно +обеспечить, чтобы они приносили достаточную пользу. Редакторы и IDE могут +напрямую подключаться к определению метода и показывать соответствующую +документацию при использовании конкретного типа, но в противном случае могут +ссылаться только на определение интерфейса. Интерфейсы — мощный инструмент, но +они имеют свою цену, поскольку сопровождающему, возможно, потребуется понять +особенности базовой реализации, чтобы правильно использовать интерфейс, что +должно быть объяснено в документации интерфейса или в месте вызова (call-site). + +Поддерживаемый код также избегает скрытия важных деталей в местах, которые легко +упустить из виду. Например, в каждой из следующих строк кода наличие или +отсутствие одного символа имеет критическое значение для понимания строки: + +```go +// Плохо: +// Использование = вместо := может полностью изменить эту строку. +if user, err = db.UserByID(userID); err != nil { + // ... +} +``` + +```go +// Плохо: +// Символ ! в середине этой строки очень легко пропустить. +leap := (year%4 == 0) && (!(year%100 == 0) || (year%400 == 0)) +``` + +Ни один из этих примеров не является неверным, но оба могут быть написаны в +более явной форме или могут иметь сопровождающий комментарий, привлекающий +внимание к важному поведению: + +```go +// Хорошо: +u, err := db.UserByID(userID) +if err != nil { + return fmt.Errorf("invalid origin user: %s", err) +} +user = u +``` + +```go +// Хорошо: +// Григорианские високосные годы — это не просто year%4 == 0. +// См. https://en.wikipedia.org/wiki/Leap_year#Algorithm. +var ( + leap4 = year%4 == 0 + leap100 = year%100 == 0 + leap400 = year%400 == 0 +) +leap := leap4 && (!leap100 || leap400) +``` + +Таким же образом вспомогательная функция, скрывающая критическую логику или +важный крайний случай (edge-case), может облегчить ситуации, когда будущее +изменение не учитывает их должным образом. + +Предсказуемые имена — еще одна особенность поддерживаемого кода. Пользователь +пакета или сопровождающий фрагмента кода должны иметь возможность предсказать +имя переменной, метода или функции в данном контексте. Параметры функций и имена +получателей (receiver) для идентичных концепций обычно должны иметь одно и то же +имя, как для понятности документации, так и для облегчения рефакторинга кода с +минимальными затратами. + +Поддерживаемый код минимизирует свои зависимости (как явные, так и неявные). +Зависимость от меньшего количества пакетов означает меньше строк кода, которые +могут повлиять на поведение. Избегание зависимостей от внутреннего или +недокументированного поведения делает код менее обременительным для поддержки +при изменении этого поведения в будущем. + +При обдумывании того, как структурировать или писать код, стоит потратить время +на размышления о том, как код может развиваться с течением времени. Если данный +подход способствует более легким и безопасным будущим изменениям, это часто +является хорошим компромиссом, даже если это означает несколько более сложный +дизайн. + +<a id="consistency"></a> + +### Согласованность (Consistency) + +Согласованный код — это код, который выглядит, ощущается и ведет себя так же, +как и аналогичный код во всей кодовой базе, в контексте команды или пакета и +даже в пределах одного файла. + +Соображения согласованности не отменяют ни один из вышеперечисленных принципов, +но если необходимо принять решение, часто полезно решить его в пользу +согласованности. + +Согласованность внутри пакета часто является наиболее важным уровнем +согласованности. Может быть очень неприятно, если одна и та же проблема решается +несколькими способами в пределах пакета или если одна концепция имеет много имен +в пределах файла. Однако даже это не должно перевешивать задокументированные +принципы стиля или глобальную согласованность. + +<a id="core"></a> + +## Основные рекомендации (Core guidelines) + +Эти рекомендации собирают наиболее важные аспекты стиля Go, которым, как +ожидается, следует весь код на Go. Мы ожидаем, что эти принципы будут изучены и +соблюдены к моменту получения права на ревью кода (readability). Они не должны +часто меняться, и новые дополнения должны преодолеть высокий барьер. + +Приведенные ниже рекомендации расширяют рекомендации из [Effective Go], которые +обеспечивают общую основу для кода на Go во всем сообществе. + +[Effective Go]: https://go.dev/doc/effective_go + +<a id="formatting"></a> + +### Форматирование (Formatting) + +Все исходные файлы Go должны соответствовать формату, выводимому инструментом +`gofmt`. Этот формат обеспечивается проверкой перед отправкой (presubmit check) +в кодовой базе Google. [Сгенерированный код] также обычно должен +форматироваться (например, с использованием [`format.Source`]), так как он также +просматривается в Code Search. + +[Сгенерированный код]: + https://docs.bazel.build/versions/main/be/general.html#genrule +[`format.Source`]: https://pkg.go.dev/go/format#Source + +<a id="mixed-caps"></a> + +### MixedCaps + +Исходный код Go использует `MixedCaps` или `mixedCaps` (верблюжий регистр, camel +case) вместо подчеркиваний (змеиный регистр, snake case) при написании составных +имен. + +Это применимо даже тогда, когда это нарушает соглашения в других языках. +Например, константа называется `MaxLength` (не `MAX_LENGTH`), если она +экспортируемая (exported), и `maxLength` (не `max_length`), если +неэкспортируемая (unexported). + +Локальные переменные считаются [неэкспортируемыми (unexported)] для целей выбора +начального регистра. + +<!--#include file="/go/g3doc/style/includes/special-name-exception.md"--> + +[неэкспортируемыми (unexported)]: https://go.dev/ref/spec#Exported_identifiers + +<a id="line-length"></a> + +### Длина строки (Line length) + +Не существует фиксированной длины строки для исходного кода Go. Если строка +кажется слишком длинной, предпочтительнее рефакторинг, чем ее разделение. Если +строка уже настолько короткая, насколько это практично, ей следует позволить +оставаться длинной. + +Не разделяйте строку: + +* Перед [изменением отступа (indentation + change)](https://neonxp.ru/pages/gostyleguide/google/decisions/#indentation-confusion) (например, объявление функции, + условие) +* Чтобы длинная строка (например, URL) поместилась в несколько более коротких + строк + +<a id="naming"></a> + +### Именование (Naming) + +Именование — это скорее искусство, чем наука. В Go имена, как правило, несколько +короче, чем во многих других языках, но применяются те же [общие принципы]. +Имена должны: + +* Не казаться [избыточными (repetitive)](https://neonxp.ru/pages/gostyleguide/google/decisions/#repetition) при + использовании +* Учитывать контекст +* Не повторять концепции, которые уже ясны + +Более конкретные рекомендации по именованию можно найти в [решениях +(https://neonxp.ru/pages/gostyleguide/google/decisions/)](https://neonxp.ru/pages/gostyleguide/google/decisions/#naming). + +[общие принципы]: + https://testing.googleblog.com/2017/10/code-health-identifiernamingpostforworl.html + +<a id="local-consistency"></a> + +### Локальная согласованность (Local consistency) + +Если в руководстве по стилю ничего не сказано по конкретному вопросу стиля, +авторы могут свободно выбирать предпочтительный стиль, если только код в +непосредственной близости (обычно в том же файле или пакете, но иногда в +пределах каталога команды или проекта) не занял последовательную позицию по +этому вопросу. + +Примеры **допустимых** соображений локального стиля: + +* Использование `%s` или `%v` для форматированного вывода ошибок +* Использование буферизованных каналов вместо мьютексов + +Примеры **недопустимых** соображений локального стиля: + +* Ограничения на длину строк для кода +* Использование библиотек тестирования на основе утверждений (assertion-based) + +Если локальный стиль противоречит руководству по стилю, но влияние на читаемость +ограничено одним файлом, это обычно будет отмечено в ревью кода, для которого +согласованное исправление выходит за рамки данного CL (change list). В этом +случае уместно завести задачу (bug) для отслеживания исправления. + +Если изменение ухудшит существующее отклонение от стиля, выставит его в большем +количестве API, увеличит количество файлов, в которых присутствует отклонение, +или внесет фактическую ошибку, то локальная согласованность больше не является +допустимым обоснованием для нарушения руководства по стилю в новом коде. В этих +случаях автору уместно либо очистить существующую кодовую базу в том же CL, либо +выполнить рефакторинг перед текущим CL, либо найти альтернативу, которая, по +крайней мере, не усугубляет локальную проблему.
\ No newline at end of file diff --git a/content/pages/gostyleguide/google/main.md b/content/pages/gostyleguide/google/main.md new file mode 100644 index 0000000..b3714ee --- /dev/null +++ b/content/pages/gostyleguide/google/main.md @@ -0,0 +1,184 @@ +--- +order: 1 +title: Google Go Style Guide — Руководство +--- + +## О руководстве + +<!--more --> + +Руководство по стилю Go и сопутствующие документы кодифицируют современные +наилучшие подходы к написанию читаемого и идиоматичного кода на Go. Следование +Руководству по стилю не является абсолютным требованием, и эти документы никогда +не будут исчерпывающими. Наша цель — минимизировать неопределённость при +написании читаемого кода на Go, чтобы новички в языке могли избежать +распространённых ошибок. Руководство по стилю также служит для унификации +рекомендаций по стилю, даваемых любым рецензентом кода Go в Google. + +| Документ | Ссылка | Основная аудитория | [Нормативный] | [Канонический] | +| ------------------------ | ----------------------------------------------------- | ------------------------ | ------------- | -------------- | +| **Руководство по стилю** | https://google.github.io/styleguide/go/guide | Все | Да | Да | +| **Решения по стилю** | https://google.github.io/styleguide/go/decisions | Наставники по читаемости | Да | Нет | +| **Лучшие практики** | https://google.github.io/styleguide/go/best-practices | Все заинтересованные | Нет | Нет | + +[Нормативный]: #нормативный +[Канонический]: #канонический + +<a id="docs"></a> + +### Документы + +1. **[Руководство по стилю](https://google.github.io/styleguide/go/guide)** + описывает основы стиля Go в Google. Этот документ является окончательным и + служит основой для рекомендаций в «Решениях по стилю» и «Лучших практиках». + +1. **[Решения по стилю](https://google.github.io/styleguide/go/decisions)** — + это более подробный документ, который суммирует решения по конкретным + вопросам стиля и, где уместно, обсуждает обоснование этих решений. + + Эти решения могут иногда меняться на основе новых данных, новых возможностей + языка, новых библиотек или возникающих паттернов, но не ожидается, что + отдельные программисты Go в Google должны следить за актуальностью этого + документа. + +1. **[Лучшие практики](https://google.github.io/styleguide/go/best-practices)** + документируют некоторые паттерны, которые развивались со временем для + решения общих задач, хорошо читаются и устойчивы к потребностям поддержки + кода. + + Эти лучшие практики не являются каноническими, но программистам Go в Google + рекомендуется использовать их там, где это возможно, для сохранения + единообразия и согласованности кодовой базы. + +Эти документы призваны: + +- Согласовать набор принципов для оценки альтернативных стилей +- Кодифицировать устоявшиеся вопросы стиля Go +- Документировать и предоставить канонические примеры идиом Go +- Документировать плюсы и минусы различных решений по стилю +- Помочь минимизировать неожиданности при рецензировании читаемости кода Go +- Помочь наставникам по читаемости использовать согласованную терминологию и + рекомендации + +Эти документы **не** призваны: + +- Быть исчерпывающим списком замечаний, которые можно дать при рецензировании + читаемости +- Перечислять все правила, которые каждый должен помнить и всегда соблюдать +- Заменять здравый смысл при использовании возможностей языка и стиля +- Оправдывать масштабные изменения для устранения различий в стиле + +Всегда будут существовать различия между разными программистами Go и между +кодовыми базами разных команд. Однако в интересах Google и Alphabet, чтобы наша +кодовая база была как можно более согласованной. (Подробнее о согласованности +см. [руководство](https://neonxp.ru/pages/gostyleguide/google/guide/#consistency)). В связи с этим не стесняйтесь вносить +улучшения стиля по мере необходимости, но вам не нужно придираться к каждому +нарушению Руководства по стилю, которое вы обнаружите. В частности, эти +документы могут меняться со временем, и это не повод вызывать лишнюю суету в +существующих кодовых базах; достаточно писать новый код, используя новейшие +лучшие практики, и со временем устранять проблемы поблизости. + +Важно понимать, что вопросы стиля по своей природе субъективны и всегда +сопряжены с компромиссами. Большая часть рекомендаций в этих документах +субъективна, но, как и в случае с `gofmt`, в обеспечиваемом ими единообразии +есть значительная ценность. Поэтому рекомендации по стилю не будут меняться без +должного обсуждения, и программистам Go в Google рекомендуется следовать +руководству по стилю, даже если они с чем-то не согласны. + +<a id="definitions"></a> + +## Определения + +Ниже приведены определения следующих слов, которые используются во всех +документах по стилю: + +- **Канонический**: Устанавливает предписывающие и долговечные правила <a + id="canonical"></a> + + В этих документах «канонический» используется для описания чего-либо, что + считается стандартом, которому должен следовать весь код (старый и новый) и + который не должен существенно меняться с течением времени. Принципы в + канонических документах должны быть понятны как авторам, так и рецензентам, + поэтому всё, что включается в канонический документ, должно соответствовать + высоким стандартам. Как таковые, канонические документы обычно короче и + предписывают меньше элементов стиля, чем неканонические документы. + + https://google.github.io/styleguide/go#canonical + +- **Нормативный**: Призван установить согласованность <a id="normative"></a> + + В этих документах «нормативный» используется для описания чего-либо, что + является согласованным элементом стиля для использования рецензентами кода + Go, чтобы предложения, терминология и обоснования были последовательными. + Эти элементы могут меняться со временем, и эти документы будут отражать + такие изменения, чтобы рецензенты могли оставаться последовательными и в + курсе событий. От авторов кода на Go не ожидается знакомства с нормативными + документами, но рецензенты будут часто использовать их в качестве + справочного материала при проверке читаемости. + + https://google.github.io/styleguide/go#normative + +- **Идиоматичный**: Распространённый и знакомый <a id="idiomatic"></a> + + В этих документах «идиоматичный» используется для обозначения чего-либо, что + широко распространено в коде на Go и стало знакомым паттерном, который легко + узнать. В целом, идиоматичный паттерн следует предпочитать неидиоматичному, + если оба служат одной цели в контексте, поскольку именно это будет наиболее + знакомо читателям. + + https://google.github.io/styleguide/go#idiomatic + +<a id="references"></a> + +## Дополнительные ссылки + +Данное руководство предполагает, что читатель знаком с [Effective Go], поскольку +оно обеспечивает общую основу для кода на Go во всём сообществе Go. + +Ниже приведены некоторые дополнительные ресурсы для тех, кто хочет +самостоятельно изучить стиль Go, и для рецензентов, желающих предоставить в +своих отзывах дополнительный контекст с ссылками. От участников процесса +проверки читаемости Go не ожидается знакомства с этими ресурсами, но они могут +упоминаться в качестве контекста при таких проверках. + +[Effective Go]: https://go.dev/doc/effective_go + +**Внешние ссылки** + +- [Спецификация языка Go](https://go.dev/ref/spec) +- [Часто задаваемые вопросы по Go](https://go.dev/doc/faq) +- [Модель памяти Go](https://go.dev/ref/mem) +- [Структуры данных в Go](https://research.swtch.com/godata) +- [Интерфейсы в Go](https://research.swtch.com/interfaces) +- [Поговорки Go](https://go-proverbs.github.io/) + +- <a id="gotip"></a> Выпуски Go Tip — следите за обновлениями. + +- <a id="unit-testing-practices"></a> Практики модульного тестирования — + следите за обновлениями. + +**Соответствующие статьи Testing-on-the-Toilet** + +- [TotT: Именование идентификаторов][tott-431] +- [TotT: Тестирование состояния vs. Тестирование взаимодействий][tott-281] +- [TotT: Эффективное тестирование][tott-324] +- [TotT: Тестирование, основанное на рисках][tott-329] +- [TotT: Детекторные тесты считаются вредными][tott-350] + +[tott-431]: https://testing.googleblog.com/2017/10/code-health-identifiernamingpostforworl.html +[tott-281]: https://testing.googleblog.com/2013/03/testing-on-toilet-testing-state-vs.html +[tott-324]: https://testing.googleblog.com/2014/05/testing-on-toilet-effective-testing.html +[tott-329]: https://testing.googleblog.com/2014/05/testing-on-toilet-risk-driven-testing.html +[tott-350]: https://testing.googleblog.com/2015/01/testing-on-toilet-change-detector-tests.html + +**Дополнительные внешние материалы** + +- [Go и догма](https://research.swtch.com/dogma) +- [Меньше — значит экспоненциально + больше](https://commandcenter.blogspot.com/2012/06/less-is-exponentially-more.html) +- [Воображение + Эсмеральды](https://commandcenter.blogspot.com/2011/12/esmereldas-imagination.html) +- [Регулярные выражения для синтаксического + анализа](https://commandcenter.blogspot.com/2011/08/regular-expressions-in-lexing-and.html) +- [Стиль Gofmt никому не нравится, но Gofmt нравится + всем](https://www.youtube.com/watch?v=PAAkCSZUG1c&t=8m43s) (YouTube) diff --git a/content/pages/gostyleguide/uber/index.md b/content/pages/gostyleguide/uber/index.md new file mode 100644 index 0000000..a8e74fd --- /dev/null +++ b/content/pages/gostyleguide/uber/index.md @@ -0,0 +1,4140 @@ +--- +order: 10 +title: Uber Go Style Guide +--- + +# Руководство по стилю Uber для Go + +Оригинал: https://github.com/uber-go/guide/blob/master/style.md + +<!--more--> + +- [Введение](#введение) +- [Рекомендации](#рекомендации) + - [Указатели на интерфейсы](#указатели-на-интерфейсы) + - [Проверка соответствия интерфейсу](#проверка-соответствия-интерфейсу) + - [Получатели и интерфейсы](#получатели-и-интерфейсы) + - [Нулевые значения мьютексов + допустимы](#нулевые-значения-мьютексов-допустимы) + - [Копируйте срезы и карты на границах](#копируйте-срезы-и-карты-на-границах) + - [Используйте `defer` для очистки](#используйте-defer-для-очистки) + - [Размер канала — один или ноль](#размер-канала-один-или-ноль) + - [Начинайте перечисления с единицы](#начинайте-перечисления-с-единицы) + - [Используйте `"time"` для работы со + временем](#используйте-time-для-работы-со-временем) + - [Ошибки](#ошибки) + - [Типы ошибок](#типы-ошибок) + - [Обёртывание ошибок](#обёртывание-ошибок) + - [Именование ошибок](#именование-ошибок) + - [Обрабатывайте ошибки один раз](#обрабатывайте-ошибки-один-раз) + - [Обрабатывайте сбои утверждения типа](#обрабатывайте-сбои-утверждения-типа) + - [Не паникуйте](#не-паникуйте) + - [Используйте go.uber.org/atomic](#используйте-gouberorgatomic) + - [Избегайте изменяемых глобальных + переменных](#избегайте-изменяемых-глобальных-переменных) + - [Избегайте встраивания типов в публичные + структуры](#избегайте-встраивания-типов-в-публичные-структуры) + - [Избегайте использования встроенных + имён](#избегайте-использования-встроенных-имён) + - [Избегайте `init()`](#избегайте-init) + - [Завершение программы в main](#завершение-программы-в-main) + - [Завершайте программу один раз](#завершайте-программу-один-раз) + - [Используйте теги полей в структурах для + сериализации](#используйте-теги-полей-в-структурах-для-сериализации) + - [Не запускайте горутины по принципу «запустил и + забыл»](#не-запускайте-горутины-по-принципу-запустил-и-забыл) + - [Дожидайтесь завершения горутин](#дожидайтесь-завершения-горутин) + - [Не используйте горутины в `init()`](#не-используйте-горутины-в-init) +- [Производительность](#производительность) + - [Предпочитайте strconv вместо fmt](#предпочитайте-strconv-вместо-fmt) + - [Избегайте повторного преобразования строк в + байты](#избегайте-повторного-преобразования-строк-в-байты) + - [Предпочитайте указание ёмкости + контейнеров](#предпочитайте-указание-ёмкости-контейнеров) +- [Стиль](#стиль) + - [Избегайте слишком длинных строк](#избегайте-слишком-длинных-строк) + - [Будьте последовательны](#будьте-последовательны) + - [Группируйте схожие объявления](#группируйте-схожие-объявления) + - [Порядок групп импорта](#порядок-групп-импорта) + - [Имена пакетов](#имена-пакетов) + - [Имена функций](#имена-функций) + - [Псевдонимы импорта](#псевдонимы-импорта) + - [Группировка и порядок функций](#группировка-и-порядок-функций) + - [Уменьшайте вложенность](#уменьшайте-вложенность) + - [Избыточный Else](#избыточный-else) + - [Объявления переменных верхнего + уровня](#объявления-переменных-верхнего-уровня) + - [Префикс \_ для неэкспортируемых глобальных + переменных](#префикс-_-для-неэкспортируемых-глобальных-переменных) + - [Встраивание в структурах](#встраивание-в-структурах) + - [Объявление локальных переменных](#объявление-локальных-переменных) + - [nil — это валидный срез](#nil-это-валидный-срез) + - [Уменьшайте область видимости + переменных](#уменьшайте-область-видимости-переменных) + - [Избегайте «голых» параметров](#избегайте-голых-параметров) + - [Используйте сырые строковые литералы, чтобы избежать + экранирования](#используйте-сырые-строковые-литералы-чтобы-избежать-экранирования) + - [Инициализация структур](#инициализация-структур) + - [Используйте имена полей для инициализации + структур](#используйте-имена-полей-для-инициализации-структур) + - [Опускайте поля с нулевыми значениями в + структурах](#опускайте-поля-с-нулевыми-значениями-в-структурах) + - [Используйте `var` для структур с нулевыми + значениями](#используйте-var-для-структур-с-нулевыми-значениями) + - [Инициализация ссылок на структуры](#инициализация-ссылок-на-структуры) + - [Инициализация карт](#инициализация-карт) + - [Строки формата вне Printf](#строки-формата-вне-printf) + - [Именование функций в стиле Printf](#именование-функций-в-стиле-printf) +- [Паттерны](#паттерны) + - [Табличные тесты](#табличные-тесты) + - [Функциональные опции](#функциональные-опции) +- [Линтинг](#линтинг) + +## Введение + +Стили — это соглашения, которые регулируют наш код. Термин «стиль» немного +неудачен, поскольку эти соглашения охватывают гораздо больше, чем просто +форматирование исходных файлов — этим занимается `gofmt`. + +Цель этого руководства — управлять этой сложностью, подробно описывая, что +следует и чего не следует делать при написании кода на Go в Uber. Эти правила +существуют, чтобы кодовая база оставалась управляемой, позволяя при этом +инженерам эффективно использовать возможности языка Go. + +Первоначально это руководство было создано [Прашантом +Варанаси](https://github.com/prashantv) и [Саймоном +Ньютоном](https://github.com/nomis52) как способ познакомить некоторых коллег с +использованием Go. С годами оно было дополнено на основе отзывов других. + +В этом документе описаны идиоматические соглашения в коде на Go, которым мы +следуем в Uber. Многие из них являются общими рекомендациями для Go, в то время +как другие расширяют внешние ресурсы: + +1. [Effective Go](https://go.dev/doc/effective_go) +2. [Go Common Mistakes](https://go.dev/wiki/CommonMistakes) +3. [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments) + +Мы стремимся к тому, чтобы примеры кода были корректны для двух последних +минорных версий [релизов Go](https://go.dev/doc/devel/release). + +Весь код должен быть свободен от ошибок при проверке с помощью `golint` и `go +vet`. Мы рекомендуем настроить ваш редактор так, чтобы он: + +- Запускал `goimports` при сохранении +- Запускал `golint` и `go vet` для проверки на ошибки + +Информацию о поддержке инструментов Go в редакторах можно найти здесь: +https://go.dev/wiki/IDEsAndTextEditorPlugins + +## Рекомендации + +### Указатели на интерфейсы + +Почти никогда не нужен указатель на интерфейс. Следует передавать интерфейсы как +значения — базовые данные при этом всё равно могут быть указателем. + +Интерфейс состоит из двух полей: + +1. Указатель на информацию, специфичную для типа. Можно думать об этом как о + «типе». +2. Указатель на данные. Если хранимые данные являются указателем, они + сохраняются напрямую. Если хранимые данные являются значением, то сохраняется + указатель на это значение. + +Если нужно, чтобы методы интерфейса изменяли базовые данные, необходимо +использовать указатель. + +### Проверка соответствия интерфейсу + +Проверяйте соответствие интерфейсу на этапе компиляции там, где это уместно. Это +включает: + +- Экспортируемые типы, которые должны реализовывать определённые интерфейсы как + часть своего API-контракта +- Экспортируемые или неэкспортируемые типы, которые являются частью коллекции + типов, реализующих один и тот же интерфейс +- Другие случаи, когда нарушение интерфейса приведёт к поломке пользователей + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +type Handler struct { + // ... +} + + + +func (h *Handler) ServeHTTP( + w http.ResponseWriter, + r *http.Request, +) { + ... +} +``` + +</td><td> + +```go +type Handler struct { + // ... +} + +var _ http.Handler = (*Handler)(nil) + +func (h *Handler) ServeHTTP( + w http.ResponseWriter, + r *http.Request, +) { + // ... +} +``` + +</td></tr> +</tbody></table> + +Выражение `var _ http.Handler = (*Handler)(nil)` не скомпилируется, если +`*Handler` перестанет соответствовать интерфейсу `http.Handler`. + +Правая часть присваивания должна быть нулевым значением утверждаемого типа. Это +`nil` для типов-указателей (например, `*Handler`), срезов и карт, и пустая +структура для типов-структур. + +```go +type LogHandler struct { + h http.Handler + log *zap.Logger +} + +var _ http.Handler = LogHandler{} + +func (h LogHandler) ServeHTTP( + w http.ResponseWriter, + r *http.Request, +) { + // ... +} +``` + +### Получатели и интерфейсы + +Методы со значением-получателем могут вызываться как на указателях, так и на +значениях. Методы с указателем-получателем могут вызываться только на указателях +или [адресуемых значениях](https://go.dev/ref/spec#Method_values). + +Например, + +```go +type S struct { + data string +} + +func (s S) Read() string { + return s.data +} + +func (s *S) Write(str string) { + s.data = str +} + +// Мы не можем получить указатели на значения, хранящиеся в картах, потому что они не являются адресуемыми значениями. +sVals := map[int]S{1: {"A"}} + +// Мы можем вызвать Read для значений, хранящихся в карте, потому что Read имеет получатель-значение, который не требует, чтобы значение было адресуемым. +sVals[1].Read() + +// Мы не можем вызвать Write для значений, хранящихся в карте, потому что Write имеет получатель-указатель, и невозможно получить указатель на значение, хранящееся в карте. +// +// sVals[1].Write("test") + +sPtrs := map[int]*S{1: {"A"}} + +// Вы можете вызвать как Read, так и Write, если карта хранит указатели, потому что указатели по своей природе адресуемы. +sPtrs[1].Read() +sPtrs[1].Write("test") +``` + +Аналогично, интерфейс может быть удовлетворён указателем, даже если метод имеет +получатель-значение. + +```go +type F interface { + f() +} + +type S1 struct{} + +func (s S1) f() {} + +type S2 struct{} + +func (s *S2) f() {} + +s1Val := S1{} +s1Ptr := &S1{} +s2Val := S2{} +s2Ptr := &S2{} + +var i F +i = s1Val +i = s1Ptr +i = s2Ptr + +// Следующее не скомпилируется, так как s2Val является значением, и для f нет получателя-значения. +// i = s2Val +``` + +В Effective Go есть хорошее описание по теме [Указатели против +значений](https://go.dev/doc/effective_go#pointers_vs_values). + +### Нулевые значения мьютексов допустимы + +Нулевое значение `sync.Mutex` и `sync.RWMutex` является допустимым, поэтому +почти никогда не нужен указатель на мьютекс. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +mu := new(sync.Mutex) +mu.Lock() +``` + +</td><td> + +```go +var mu sync.Mutex +mu.Lock() +``` + +</td></tr> +</tbody></table> + +Если вы используете структуру по указателю, то мьютекс должен быть не +указателем, а полем в ней. Не встраивайте мьютекс в структуру, даже если +структура не экспортируется. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +type SMap struct { + sync.Mutex + + data map[string]string +} + +func NewSMap() *SMap { + return &SMap{ + data: make(map[string]string), + } +} + +func (m *SMap) Get(k string) string { + m.Lock() + defer m.Unlock() + + return m.data[k] +} +``` + +</td><td> + +```go +type SMap struct { + mu sync.Mutex + + data map[string]string +} + +func NewSMap() *SMap { + return &SMap{ + data: make(map[string]string), + } +} + +func (m *SMap) Get(k string) string { + m.mu.Lock() + defer m.mu.Unlock() + + return m.data[k] +} +``` + +</td></tr> + +<tr><td> + +Поле `Mutex`, а также методы `Lock` и `Unlock` непреднамеренно становятся частью +публичного API `SMap`. + +</td><td> + +Мьютекс и его методы являются деталями реализации `SMap`, скрытыми от его +вызывающих сторон. + +</td></tr> +</tbody></table> + +### Копируйте срезы и карты на границах + +Срезы и карты содержат указатели на базовые данные, поэтому будьте осторожны в +ситуациях, когда их нужно скопировать. + +#### Получение срезов и карт + +Помните, что пользователи могут изменить карту или срез, которые вы получили в +качестве аргумента, если сохраните ссылку на них. + +<table> +<thead><tr><th>Плохо</th> <th>Хорошо</th></tr></thead> +<tbody> +<tr> +<td> + +```go +func (d *Driver) SetTrips(trips []Trip) { + d.trips = trips +} + +trips := ... +d1.SetTrips(trips) + +// Вы хотели изменить d1.trips? +trips[0] = ... +``` + +</td> +<td> + +```go +func (d *Driver) SetTrips(trips []Trip) { + d.trips = make([]Trip, len(trips)) + copy(d.trips, trips) +} + +trips := ... +d1.SetTrips(trips) + +// Теперь мы можем изменить trips[0], не затрагивая d1.trips. +trips[0] = ... +``` + +</td> +</tr> + +</tbody> +</table> + +#### Возврат срезов и карт + +Аналогично, будьте осторожны с модификациями карт или срезов, раскрывающих +внутреннее состояние. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +type Stats struct { + mu sync.Mutex + counters map[string]int +} + +// Snapshot возвращает текущую статистику. +func (s *Stats) Snapshot() map[string]int { + s.mu.Lock() + defer s.mu.Unlock() + + return s.counters +} + +// snapshot больше не защищён мьютексом, поэтому любой доступ к snapshot подвержен состоянию гонки. +snapshot := stats.Snapshot() +``` + +</td><td> + +```go +type Stats struct { + mu sync.Mutex + counters map[string]int +} + +func (s *Stats) Snapshot() map[string]int { + s.mu.Lock() + defer s.mu.Unlock() + + result := make(map[string]int, len(s.counters)) + for k, v := range s.counters { + result[k] = v + } + return result +} + +// Snapshot теперь является копией. +snapshot := stats.Snapshot() +``` + +</td></tr> +</tbody></table> + +### Используйте `defer` для очистки + +Используйте `defer` для очистки ресурсов, таких как файлы и блокировки. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +p.Lock() +if p.count < 10 { + p.Unlock() + return p.count +} + +p.count++ +newCount := p.count +p.Unlock() + +return newCount + +// легко пропустить разблокировки из-за множественных возвратов +``` + +</td><td> + +```go +p.Lock() +defer p.Unlock() + +if p.count < 10 { + return p.count +} + +p.count++ +return p.count + +// более читаемо +``` + +</td></tr> +</tbody></table> + +`defer` имеет крайне малые накладные расходы, и его следует избегать только если +вы можете доказать, что время выполнения вашей функции измеряется в +наносекундах. Выигрыш в читаемости от использования `defer` стоит той мизерной +стоимости, которую он вносит. Это особенно верно для больших методов, где +присутствуют не только простые операции доступа к памяти, а другие вычисления +более значимы, чем `defer`. + +### Размер канала — один или ноль + +Каналы обычно должны иметь размер один или быть небуферизированными. По +умолчанию каналы небуферизированы и имеют размер ноль. Любой другой размер +должен подвергаться тщательному анализу. Подумайте, как определяется размер, что +предотвращает заполнение канала под нагрузкой и блокировку писателей, и что +происходит, когда это случается. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +// Должно хватить на всех! +c := make(chan int, 64) +``` + +</td><td> + +```go +// Размер один +c := make(chan int, 1) // или +// Небуферизированный канал, размер ноль +c := make(chan int) +``` + +</td></tr> +</tbody></table> + +### Начинайте перечисления с единицы + +Стандартный способ введения перечислений в Go — объявление пользовательского +типа и группы `const` с `iota`. Поскольку переменные имеют значение по умолчанию +0, обычно следует начинать перечисления с ненулевого значения. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +type Operation int + +const ( + Add Operation = iota + Subtract + Multiply +) + +// Add=0, Subtract=1, Multiply=2 +``` + +</td><td> + +```go +type Operation int + +const ( + Add Operation = iota + 1 + Subtract + Multiply +) + +// Add=1, Subtract=2, Multiply=3 +``` + +</td></tr> +</tbody></table> + +Бывают случаи, когда использование нулевого значения имеет смысл, например, +когда случай с нулевым значением является желаемым поведением по умолчанию. + +```go +type LogOutput int + +const ( + LogToStdout LogOutput = iota + LogToFile + LogToRemote +) + +// LogToStdout=0, LogToFile=1, LogToRemote=2 +``` + +<!-- TODO: раздел о String методах для перечислений --> + +### Используйте `"time"` для работы со временем + +Время — это сложно. Часто делаются неверные предположения о времени, включая +следующие. + +1. В сутках 24 часа +2. В часе 60 минут +3. В неделе 7 дней +4. В году 365 дней +5. [И многое + другое](https://infiniteundo.com/post/25326999628/falsehoods-programmers-believe-about-time) + +Например, _1_ означает, что добавление 24 часов к моменту времени не всегда даст +новый календарный день. + +Поэтому всегда используйте пакет [`"time"`](https://pkg.go.dev/time) при работе +со временем, так как он помогает безопаснее и точнее справляться с этими +неверными предположениями. + +#### Используйте `time.Time` для моментов времени + +Используйте [`time.Time`](https://pkg.go.dev/time#Time) при работе с моментами +времени и методы `time.Time` для сравнения, добавления или вычитания времени. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +func isActive(now, start, stop int) bool { + return start <= now && now < stop +} +``` + +</td><td> + +```go +func isActive(now, start, stop time.Time) bool { + return (start.Before(now) || start.Equal(now)) && now.Before(stop) +} +``` + +</td></tr> +</tbody></table> + +#### Используйте `time.Duration` для промежутков времени + +Используйте [`time.Duration`](https://pkg.go.dev/time#Duration) при работе с +промежутками времени. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +func poll(delay int) { + for { + // ... + time.Sleep(time.Duration(delay) * time.Millisecond) + } +} + +poll(10) // это секунды или миллисекунды? +``` + +</td><td> + +```go +func poll(delay time.Duration) { + for { + // ... + time.Sleep(delay) + } +} + +poll(10*time.Second) +``` + +</td></tr> +</tbody></table> + +Возвращаясь к примеру добавления 24 часов к моменту времени, метод, который мы +используем для добавления времени, зависит от намерения. Если мы хотим получить +то же время суток, но на следующий календарный день, следует использовать +[`Time.AddDate`](https://pkg.go.dev/time#Time.AddDate). Однако, если мы хотим +момент времени, гарантированно наступающий через 24 часа после предыдущего, +следует использовать [`Time.Add`](https://pkg.go.dev/time#Time.Add). + +```go +newDay := t.AddDate(0 /* years */, 0 /* months */, 1 /* days */) +maybeNewDay := t.Add(24 * time.Hour) +``` + +#### Используйте `time.Time` и `time.Duration` с внешними системами + +По возможности используйте `time.Duration` и `time.Time` при взаимодействии с +внешними системами. Например: + +- Флаги командной строки: [`flag`](https://pkg.go.dev/flag) поддерживает + `time.Duration` через + [`time.ParseDuration`](https://pkg.go.dev/time#ParseDuration) +- JSON: [`encoding/json`](https://pkg.go.dev/encoding/json) поддерживает + кодирование `time.Time` как строки [RFC + 3339](https://tools.ietf.org/html/rfc3339) через свой [`UnmarshalJSON` + метод](https://pkg.go.dev/time#Time.UnmarshalJSON) +- SQL: [`database/sql`](https://pkg.go.dev/database/sql) поддерживает + преобразование столбцов `DATETIME` или `TIMESTAMP` в `time.Time` и обратно, + если базовый драйвер поддерживает это. +- YAML: [`gopkg.in/yaml.v2`](https://pkg.go.dev/gopkg.in/yaml.v2) поддерживает + `time.Time` как строку [RFC 3339](https://tools.ietf.org/html/rfc3339) и + `time.Duration` через + [`time.ParseDuration`](https://pkg.go.dev/time#ParseDuration). + +Если невозможно использовать `time.Duration` в этих взаимодействиях, используйте +`int` или `float64` и включайте единицу измерения в имя поля. + +Например, так как `encoding/json` не поддерживает `time.Duration`, единица +измерения включается в имя поля. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +// {"interval": 2} +type Config struct { + Interval int `json:"interval"` +} +``` + +</td><td> + +```go +// {"intervalMillis": 2000} +type Config struct { + IntervalMillis int `json:"intervalMillis"` +} +``` + +</td></tr> +</tbody></table> + +Если невозможно использовать `time.Time` в этих взаимодействиях, если не +согласована альтернатива, используйте `string` и форматируйте временные метки в +соответствии с [RFC 3339](https://tools.ietf.org/html/rfc3339). Этот формат +используется по умолчанию в +[`Time.UnmarshalText`](https://pkg.go.dev/time#Time.UnmarshalText) и доступен +для использования в `Time.Format` и `time.Parse` через +[`time.RFC3339`](https://pkg.go.dev/time#RFC3339). + +Хотя на практике это обычно не проблема, имейте в виду, что пакет `"time"` не +поддерживает разбор временных меток с високосными секундами +([8728](https://github.com/golang/go/issues/8728)), а также не учитывает +високосные секунды в вычислениях +([15190](https://github.com/golang/go/issues/15190)). Если вы сравниваете два +момента времени, разница не будет включать високосные секунды, которые могли +произойти между этими моментами. + +### Ошибки + +#### Типы ошибок + +Есть несколько вариантов объявления ошибок. Рассмотрите следующее, прежде чем +выбрать вариант, наиболее подходящий для вашего случая. + +- Нужно ли вызывающей стороне сопоставлять ошибку, чтобы обработать её? Если + да, мы должны поддерживать функции [`errors.Is`](https://pkg.go.dev/errors#Is) + или [`errors.As`](https://pkg.go.dev/errors#As) путём объявления переменной + ошибки верхнего уровня или пользовательского типа. +- Сообщение об ошибке — статическая строка или динамическая строка, требующая + контекстной информации? Для первого случая можно использовать + [`errors.New`](https://pkg.go.dev/errors#New), но для второго необходимо + использовать [`fmt.Errorf`](https://pkg.go.dev/fmt#Errorf) или + пользовательский тип ошибки. +- Мы распространяем новую ошибку, возвращённую нижележащей функцией? Если да, + см. [раздел об обёртывании ошибок](#обёртывание-ошибок). + +| Сопоставление ошибок? | Сообщение об ошибке | Рекомендация | +| --------------------- | ------------------- | -------------------------------------------------------------------------- | +| Нет | статическое | [`errors.New`](https://pkg.go.dev/errors#New) | +| Нет | динамическое | [`fmt.Errorf`](https://pkg.go.dev/fmt#Errorf) | +| Да | статическое | переменная верхнего уровня с [`errors.New`](https://pkg.go.dev/errors#New) | +| Да | динамическое | пользовательский тип `error` | + +Например, используйте [`errors.New`](https://pkg.go.dev/errors#New) для ошибки +со статической строкой. Экспортируйте эту ошибку как переменную, чтобы +поддерживать её сопоставление с `errors.Is`, если вызывающей стороне нужно +сопоставить и обработать эту ошибку. + +<table> +<thead><tr><th>Без сопоставления ошибок</th><th>С сопоставлением ошибок</th></tr></thead> +<tbody> +<tr><td> + +```go +// package foo + +func Open() error { + return errors.New("could not open") +} + +// package bar + +if err := foo.Open(); err != nil { + // Не можем обработать ошибку. + panic("unknown error") +} +``` + +</td><td> + +```go +// package foo + +var ErrCouldNotOpen = errors.New("could not open") + +func Open() error { + return ErrCouldNotOpen +} + +// package bar + +if err := foo.Open(); err != nil { + if errors.Is(err, foo.ErrCouldNotOpen) { + // обработать ошибку + } else { + panic("unknown error") + } +} +``` + +</td></tr> +</tbody></table> + +Для ошибки с динамической строкой используйте +[`fmt.Errorf`](https://pkg.go.dev/fmt#Errorf), если вызывающей стороне не нужно +её сопоставлять, и пользовательский `error`, если нужно. + +<table> +<thead><tr><th>Без сопоставления ошибок</th><th>С сопоставлением ошибок</th></tr></thead> +<tbody> +<tr><td> + +```go +// package foo + +func Open(file string) error { + return fmt.Errorf("file %q not found", file) +} + +// package bar + +if err := foo.Open("testfile.txt"); err != nil { + // Не можем обработать ошибку. + panic("unknown error") +} +``` + +</td><td> + +```go +// package foo + +type NotFoundError struct { + File string +} + +func (e *NotFoundError) Error() string { + return fmt.Sprintf("file %q not found", e.File) +} + +func Open(file string) error { + return &NotFoundError{File: file} +} + + +// package bar + +if err := foo.Open("testfile.txt"); err != nil { + var notFound *NotFoundError + if errors.As(err, ¬Found) { + // обработать ошибку + } else { + panic("unknown error") + } +} +``` + +</td></tr> +</tbody></table> + +Обратите внимание, что если вы экспортируете переменные или типы ошибок из +пакета, они станут частью публичного API пакета. + +#### Обёртывание ошибок + +Есть три основных варианта распространения ошибок при неудачном вызове: + +- вернуть исходную ошибку как есть +- добавить контекст с помощью `fmt.Errorf` и глагола `%w` +- добавить контекст с помощью `fmt.Errorf` и глагола `%v` + +Возвращайте исходную ошибку как есть, если нечего добавить к контексту. Это +сохраняет исходный тип и сообщение ошибки. Это хорошо подходит для случаев, +когда базовое сообщение об ошибке содержит достаточно информации для +отслеживания её происхождения. + +В противном случае добавляйте контекст к сообщению об ошибке, где это возможно, +чтобы вместо расплывчатой ошибки вроде "connection refused" вы получали более +полезные ошибки, такие как "call service foo: connection refused". + +Используйте `fmt.Errorf` для добавления контекста к вашим ошибкам, выбирая между +глаголами `%w` или `%v` в зависимости от того, должна ли вызывающая сторона +иметь возможность сопоставить и извлечь базовую причину. + +- Используйте `%w`, если вызывающая сторона должна иметь доступ к базовой + ошибке. Это хороший вариант по умолчанию для большинства обёрнутых ошибок, но + имейте в виду, что вызывающие стороны могут начать полагаться на это + поведение. Поэтому для случаев, когда обёрнутая ошибка является известной + `var` или типом, документируйте и тестируйте это как часть контракта вашей + функции. +- Используйте `%v`, чтобы скрыть базовую ошибку. Вызывающие стороны не смогут её + сопоставить, но вы сможете переключиться на `%w` в будущем, если потребуется. + +При добавлении контекста к возвращаемым ошибкам сохраняйте контекст кратким, +избегая фраз типа "failed to", которые констатируют очевидное и накапливаются по +мере всплытия ошибки по стеку: + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +s, err := store.New() +if err != nil { + return fmt.Errorf( + "failed to create new store: %w", err) +} +``` + +</td><td> + +```go +s, err := store.New() +if err != nil { + return fmt.Errorf( + "new store: %w", err) +} +``` + +</td></tr><tr><td> + +```plain +failed to x: failed to y: failed to create new store: the error +``` + +</td><td> + +```plain +x: y: new store: the error +``` + +</td></tr> +</tbody></table> + +Однако, как только ошибка отправляется в другую систему, должно быть понятно, +что сообщение является ошибкой (например, тег `err` или префикс "Failed" в +логах). + +См. также [Don't just check errors, handle them +gracefully](https://dave.cheney.net/2016/04/27/dont-just-check-errors-handle-them-gracefully). + +#### Именование ошибок + +Для значений ошибок, хранящихся как глобальные переменные, используйте префикс +`Err` или `err` в зависимости от того, экспортируются они или нет. Это указание +заменяет [Префикс \_ для неэкспортируемых глобальных +переменных](#префикс-_-для-неэкспортируемых-глобальных-переменных). + +```go +var ( + // Следующие две ошибки экспортируются, чтобы пользователи этого пакета могли сопоставлять их с errors.Is. + + ErrBrokenLink = errors.New("link is broken") + ErrCouldNotOpen = errors.New("could not open") + + // Эта ошибка не экспортируется, потому что мы не хотим делать её частью нашего публичного API. Мы всё ещё можем использовать её внутри пакета с errors.Is. + + errNotFound = errors.New("not found") +) +``` + +Для пользовательских типов ошибок используйте суффикс `Error` вместо этого. + +```go +// Аналогично, эта ошибка экспортируется, чтобы пользователи этого пакета могли сопоставлять её с errors.As. + +type NotFoundError struct { + File string +} +func (e *NotFoundError) Error() string { + return fmt.Sprintf("file %q not found", e.File) +} + +// А эта ошибка не экспортируется, потому что мы не хотим делать её частью публичного API. Мы всё ещё можем использовать её внутри пакета с errors.As. + +type resolveError struct { + Path string +} + +func (e *resolveError) Error() string { + return fmt.Sprintf("resolve %q", e.Path) +} +``` + +#### Обрабатывайте ошибки один раз + +Когда вызывающая сторона получает ошибку от вызываемой функции, она может +обработать её различными способами в зависимости от того, что она знает об +ошибке. + +К ним относятся, но не ограничиваются: + +- если контракт вызываемой функции определяет конкретные ошибки, сопоставить + ошибку с `errors.Is` или `errors.As` и обработать ветви по-разному +- если ошибка является восстанавливаемой, залогировать ошибку и выполнить + graceful degradation +- если ошибка представляет собой отказ в предметной области, вернуть чётко + определённую ошибку +- вернуть ошибку, либо [обёрнутую](#обёртывание-ошибок), либо как есть + +Независимо от того, как вызывающая сторона обрабатывает ошибку, обычно она +должна обрабатывать каждую ошибку только один раз. Вызывающая сторона не должна, +например, логировать ошибку, а затем возвращать её, потому что _её_ вызывающие +стороны тоже могут обработать ошибку. + +Например, рассмотрим следующие случаи: + +<table> +<thead><tr><th>Описание</th><th>Код</th></tr></thead> +<tbody> +<tr><td> + +**Плохо**: Логировать ошибку и возвращать её + +Вызывающие стороны выше по стеку, вероятно, предпримут аналогичные действия с +ошибкой. Это приведёт к большому количеству шума в логах приложения при малой +пользе. + +</td><td> + +```go +u, err := getUser(id) +if err != nil { + // ПЛОХО: см. описание + log.Printf("Could not get user %q: %v", id, err) + return err +} +``` + +</td></tr> +<tr><td> + +**Хорошо**: Обернуть ошибку и вернуть её + +Вызывающие стороны выше по стеку обработают ошибку. Использование `%w` +гарантирует, что они смогут сопоставить ошибку с `errors.Is` или `errors.As`, +если это уместно. + +</td><td> + +```go +u, err := getUser(id) +if err != nil { + return fmt.Errorf("get user %q: %w", id, err) +} +``` + +</td></tr> +<tr><td> + +**Хорошо**: Логировать ошибку и выполнить graceful degradation + +Если операция не является строго необходимой, мы можем обеспечить +деградировавший, но работающий опыт, восстановившись после ошибки. + +</td><td> + +```go +if err := emitMetrics(); err != nil { + // Неудача при записи метрик не должна ломать приложение. + log.Printf("Could not emit metrics: %v", err) +} + +``` + +</td></tr> +<tr><td> + +**Хорошо**: Сопоставить ошибку и выполнить graceful degradation + +Если вызываемая функция определяет конкретную ошибку в своём контракте и сбой +является восстанавливаемым, сопоставьте этот случай ошибки и выполните graceful +degradation. Для всех остальных случаев оберните ошибку и верните её. + +Вызывающие стороны выше по стеку обработают другие ошибки. + +</td><td> + +```go +tz, err := getUserTimeZone(id) +if err != nil { + if errors.Is(err, ErrUserNotFound) { + // Пользователь не существует. Используем UTC. + tz = time.UTC + } else { + return fmt.Errorf("get user %q: %w", id, err) + } +} +``` + +</td></tr> +</tbody></table> + +### Обрабатывайте сбои утверждения типа + +Форма утверждения типа с одним возвращаемым значением вызовет панику при +неверном типе. Поэтому всегда используйте идиому "comma ok". + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +t := i.(string) +``` + +</td><td> + +```go +t, ok := i.(string) +if !ok { + // обработать ошибку корректно +} +``` + +</td></tr> +</tbody></table> + +<!-- TODO: Есть несколько ситуаций, где форма с одним присваиванием допустима. --> + +### Не паникуйте + +Код, работающий в production, должен избегать паник. Паники являются основной +причиной [каскадных сбоев](https://en.wikipedia.org/wiki/Cascading_failure). +Если возникает ошибка, функция должна вернуть ошибку и позволить вызывающей +стороне решить, как её обработать. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +func run(args []string) { + if len(args) == 0 { + panic("an argument is required") + } + // ... +} + +func main() { + run(os.Args[1:]) +} +``` + +</td><td> + +```go +func run(args []string) error { + if len(args) == 0 { + return errors.New("an argument is required") + } + // ... + return nil +} + +func main() { + if err := run(os.Args[1:]); err != nil { + fmt.Fprintln(os.Stderr, err) + os.Exit(1) + } +} +``` + +</td></tr> +</tbody></table> + +Panic/recover — это не стратегия обработки ошибок. Программа должна паниковать +только при возникновении чего-то невосстановимого, например, разыменовании nil. +Исключением является инициализация программы: проблемы при запуске программы, +которые должны её завершить, могут вызывать панику. + +```go +var _statusTemplate = template.Must(template.New("name").Parse("_statusHTML")) +``` + +Даже в тестах предпочитайте `t.Fatal` или `t.FailNow` вместо паник, чтобы +гарантировать, что тест будет помечен как неудачный. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +// func TestFoo(t *testing.T) + +f, err := os.CreateTemp("", "test") +if err != nil { + panic("failed to set up test") +} +``` + +</td><td> + +```go +// func TestFoo(t *testing.T) + +f, err := os.CreateTemp("", "test") +if err != nil { + t.Fatal("failed to set up test") +} +``` + +</td></tr> +</tbody></table> + +### Используйте go.uber.org/atomic + +Атомарные операции с пакетом [sync/atomic](https://pkg.go.dev/sync/atomic) +работают с базовыми типами (`int32`, `int64` и т.д.), поэтому легко забыть +использовать атомарную операцию для чтения или изменения переменных. + +[go.uber.org/atomic](https://pkg.go.dev/go.uber.org/atomic) добавляет +безопасность типов к этим операциям, скрывая базовый тип. Кроме того, он +включает удобный тип `atomic.Bool`. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +type foo struct { + running int32 // atomic +} + +func (f* foo) start() { + if atomic.SwapInt32(&f.running, 1) == 1 { + // уже работает… + return + } + // запустить Foo +} + +func (f *foo) isRunning() bool { + return f.running == 1 // состояние гонки! +} +``` + +</td><td> + +```go +type foo struct { + running atomic.Bool +} + +func (f *foo) start() { + if f.running.Swap(true) { + // уже работает… + return + } + // запустить Foo +} + +func (f *foo) isRunning() bool { + return f.running.Load() +} +``` + +</td></tr> +</tbody></table> + +### Избегайте изменяемых глобальных переменных + +Избегайте изменения глобальных переменных, отдавая предпочтение внедрению +зависимостей. Это относится как к указателям на функции, так и к другим видам +значений. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +// sign.go + +var _timeNow = time.Now + +func sign(msg string) string { + now := _timeNow() + return signWithTime(msg, now) +} +``` + +</td><td> + +```go +// sign.go + +type signer struct { + now func() time.Time +} + +func newSigner() *signer { + return &signer{ + now: time.Now, + } +} + +func (s *signer) Sign(msg string) string { + now := s.now() + return signWithTime(msg, now) +} +``` + +</td></tr> +<tr><td> + +```go +// sign_test.go + +func TestSign(t *testing.T) { + oldTimeNow := _timeNow + _timeNow = func() time.Time { + return someFixedTime + } + defer func() { _timeNow = oldTimeNow }() + + assert.Equal(t, want, sign(give)) +} +``` + +</td><td> + +```go +// sign_test.go + +func TestSigner(t *testing.T) { + s := newSigner() + s.now = func() time.Time { + return someFixedTime + } + + assert.Equal(t, want, s.Sign(give)) +} +``` + +</td></tr> +</tbody></table> + +### Избегайте встраивания типов в публичные структуры + +Такие встроенные типы раскрывают детали реализации, препятствуют эволюции типов +и затрудняют чтение документации. + +Предположим, вы реализовали различные типы списков, используя общий +`AbstractList`. Избегайте встраивания `AbstractList` в ваши конкретные +реализации списков. Вместо этого напишите вручную только методы вашего +конкретного списка, которые будут делегировать вызовы абстрактному списку. + +```go +type AbstractList struct {} + +// Add добавляет сущность в список. +func (l *AbstractList) Add(e Entity) { + // ... +} + +// Remove удаляет сущность из списка. +func (l *AbstractList) Remove(e Entity) { + // ... +} +``` + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +// ConcreteList — это список сущностей. +type ConcreteList struct { + *AbstractList +} +``` + +</td><td> + +```go +// ConcreteList — это список сущностей. +type ConcreteList struct { + list *AbstractList +} + +// Add добавляет сущность в список. +func (l *ConcreteList) Add(e Entity) { + l.list.Add(e) +} + +// Remove удаляет сущность из списка. +func (l *ConcreteList) Remove(e Entity) { + l.list.Remove(e) +} +``` + +</td></tr> +</tbody></table> + +Go позволяет [встраивание типов](https://go.dev/doc/effective_go#embedding) как +компромисс между наследованием и композицией. Внешний тип получает неявные копии +методов встроенного типа. Эти методы по умолчанию делегируют вызовы тому же +методу встроенного экземпляра. + +Структура также получает поле с тем же именем, что и тип. Таким образом, если +встроенный тип является публичным, поле также является публичным. Для сохранения +обратной совместимости каждая будущая версия внешнего типа должна сохранять +встроенный тип. + +Встраивание типа редко необходимо. Это удобство, которое помогает избежать +написания утомительных делегирующих методов. + +Даже встраивание совместимого интерфейса `AbstractList` вместо структуры дало бы +разработчику больше гибкости для изменений в будущем, но всё равно раскрыло бы +деталь, что конкретные списки используют абстрактную реализацию. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +// AbstractList — это обобщённая реализация для различных видов списков сущностей. +type AbstractList interface { + Add(Entity) + Remove(Entity) +} + +// ConcreteList — это список сущностей. +type ConcreteList struct { + AbstractList +} +``` + +</td><td> + +```go +// ConcreteList — это список сущностей. +type ConcreteList struct { + list AbstractList +} + +// Add добавляет сущность в список. +func (l *ConcreteList) Add(e Entity) { + l.list.Add(e) +} + +// Remove удаляет сущность из списка. +func (l *ConcreteList) Remove(e Entity) { + l.list.Remove(e) +} +``` + +</td></tr> +</tbody></table> + +И в случае со встроенной структурой, и со встроенным интерфейсом встроенный тип +накладывает ограничения на эволюцию типа. + +- Добавление методов во встроенный интерфейс — это breaking change. +- Удаление методов из встроенной структуры — это breaking change. +- Удаление встроенного типа — это breaking change. +- Замена встроенного типа, даже на альтернативу, удовлетворяющую тому же + интерфейсу, — это breaking change. + +Хотя написание этих делегирующих методов утомительно, дополнительные усилия +скрывают деталь реализации, оставляют больше возможностей для изменений, а также +устраняют косвенность при обнаружении полного интерфейса `List` в документации. + +### Избегайте использования встроенных имён + +[Спецификация языка Go](https://go.dev/ref/spec) описывает несколько встроенных, +[предобъявленных +идентификаторов](https://go.dev/ref/spec#Predeclared_identifiers), которые не +должны использоваться как имена в программах на Go. + +В зависимости от контекста повторное использование этих идентификаторов в +качестве имён либо затеняет оригинал в текущей лексической области видимости (и +любых вложенных областях), либо делает затронутый код запутанным. В лучшем +случае компилятор пожалуется; в худшем — такой код может привести к скрытым, +трудноуловимым ошибкам. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +var error string +// `error` затеняет встроенный идентификатор + +// или + +func handleErrorMessage(error string) { + // `error` затеняет встроенный идентификатор +} +``` + +</td><td> + +```go +var errorMessage string +// `error` ссылается на встроенный идентификатор + +// или + +func handleErrorMessage(msg string) { + // `error` ссылается на встроенный идентификатор +} +``` + +</td></tr> +<tr><td> + +```go +type Foo struct { + // Хотя технически эти поля не создают затенение, поиск по строкам `error` или `string` теперь неоднозначен. + error error + string string +} + +func (f Foo) Error() error { + // `error` и `f.error` визуально похожи + return f.error +} + +func (f Foo) String() string { + // `string` и `f.string` визуально похожи + return f.string +} +``` + +</td><td> + +```go +type Foo struct { + // `error` и `string` теперь однозначны. + err error + str string +} + +func (f Foo) Error() error { + return f.err +} + +func (f Foo) String() string { + return f.str +} +``` + +</td></tr> +</tbody></table> + +Обратите внимание, что компилятор не будет генерировать ошибки при использовании +предобъявленных идентификаторов, но такие инструменты, как `go vet`, должны +корректно указывать на эти и другие случаи затенения. + +### Избегайте `init()` + +Избегайте `init()` там, где это возможно. Когда `init()` неизбежен или +желателен, код должен пытаться: + +1. Быть полностью детерминированным, независимо от среды программы или вызова. +2. Избегать зависимости от порядка или побочных эффектов других функций + `init()`. Хотя порядок `init()` хорошо известен, код может меняться, и + поэтому зависимости между функциями `init()` могут сделать код хрупким и + подверженным ошибкам. +3. Избегать доступа или манипуляции глобальным состоянием или состоянием + окружения, таким как информация о машине, переменные окружения, рабочая + директория, аргументы/вводы программы и т.д. +4. Избегать ввода-вывода, включая файловую систему, сеть и системные вызовы. + +Код, который не может удовлетворить этим требованиям, вероятно, должен быть +вспомогательной функцией, вызываемой как часть `main()` (или в другом месте +жизненного цикла программы), или быть написан как часть самого `main()`. В +частности, библиотеки, предназначенные для использования другими программами, +должны особенно тщательно следить за полной детерминированностью и не выполнять +"init magic". + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +type Foo struct { + // ... +} + +var _defaultFoo Foo + +func init() { + _defaultFoo = Foo{ + // ... + } +} +``` + +</td><td> + +```go +var _defaultFoo = Foo{ + // ... +} + +// или, лучше, для тестируемости: + +var _defaultFoo = defaultFoo() + +func defaultFoo() Foo { + return Foo{ + // ... + } +} +``` + +</td></tr> +<tr><td> + +```go +type Config struct { + // ... +} + +var _config Config + +func init() { + // Плохо: зависит от текущей директории + cwd, _ := os.Getwd() + + // Плохо: ввод-вывод + raw, _ := os.ReadFile( + path.Join(cwd, "config", "config.yaml"), + ) + + yaml.Unmarshal(raw, &_config) +} +``` + +</td><td> + +```go +type Config struct { + // ... +} + +func loadConfig() Config { + cwd, err := os.Getwd() + // обработать err + + raw, err := os.ReadFile( + path.Join(cwd, "config", "config.yaml"), + ) + // обработать err + + var config Config + yaml.Unmarshal(raw, &config) + + return config +} +``` + +</td></tr> +</tbody></table> + +Учитывая вышесказанное, некоторые ситуации, в которых `init()` может быть +предпочтительнее или необходим, включают: + +- Сложные выражения, которые нельзя представить в виде одиночных присваиваний. +- Подключаемые хуки, такие как диалекты `database/sql`, регистры типов + кодирования и т.д. +- Оптимизации для [Google Cloud + Functions](https://cloud.google.com/functions/docs/bestpractices/tips#use_global_variables_to_reuse_objects_in_future_invocations) + и другие формы детерминированного предварительного вычисления. + +### Завершение программы в main + +Программы на Go используют [`os.Exit`](https://pkg.go.dev/os#Exit) или +[`log.Fatal*`](https://pkg.go.dev/log#Fatal) для немедленного завершения. +(Паника — нехороший способ завершения программ, пожалуйста, [не +паникуйте](#не-паникуйте).) + +Вызывайте `os.Exit` или `log.Fatal*` **только в `main()`**. Все остальные +функции должны возвращать ошибки для сигнализации о сбое. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +func main() { + body := readFile(path) + fmt.Println(body) +} + +func readFile(path string) string { + f, err := os.Open(path) + if err != nil { + log.Fatal(err) + } + + b, err := io.ReadAll(f) + if err != nil { + log.Fatal(err) + } + + return string(b) +} +``` + +</td><td> + +```go +func main() { + body, err := readFile(path) + if err != nil { + log.Fatal(err) + } + fmt.Println(body) +} + +func readFile(path string) (string, error) { + f, err := os.Open(path) + if err != nil { + return "", err + } + + b, err := io.ReadAll(f) + if err != nil { + return "", err + } + + return string(b), nil +} +``` + +</td></tr> +</tbody></table> + +Обоснование: Программы с несколькими функциями, которые завершают выполнение, +создают несколько проблем: + +- Неочевидный поток управления: любая функция может завершить программу, поэтому + становится трудно рассуждать о потоке управления. +- Сложность тестирования: функция, завершающая программу, также завершит тест, + который её вызывает. Это делает функцию трудной для тестирования и создаёт + риск пропуска других тестов, которые ещё не были запущены `go test`. +- Пропущенная очистка: когда функция завершает программу, она пропускает вызовы + функций, поставленные в очередь с операторами `defer`. Это добавляет риск + пропуска важных задач очистки. + +#### Завершайте программу один раз + +По возможности старайтесь вызывать `os.Exit` или `log.Fatal` **не более одного +раза** в вашем `main()`. Если есть несколько сценариев ошибок, которые +останавливают выполнение программы, поместите эту логику в отдельную функцию и +возвращайте из неё ошибки. + +Это приводит к сокращению функции `main()` и помещению всей ключевой +бизнес-логики в отдельную, тестируемую функцию. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +package main + +func main() { + args := os.Args[1:] + if len(args) != 1 { + log.Fatal("missing file") + } + name := args[0] + + f, err := os.Open(name) + if err != nil { + log.Fatal(err) + } + defer f.Close() + + // Если мы вызовем log.Fatal после этой строки, f.Close не будет вызван. + + b, err := io.ReadAll(f) + if err != nil { + log.Fatal(err) + } + + // ... +} +``` + +</td><td> + +```go +package main + +func main() { + if err := run(); err != nil { + log.Fatal(err) + } +} + +func run() error { + args := os.Args[1:] + if len(args) != 1 { + return errors.New("missing file") + } + name := args[0] + + f, err := os.Open(name) + if err != nil { + return err + } + defer f.Close() + + b, err := io.ReadAll(f) + if err != nil { + return err + } + + // ... +} +``` + +</td></tr> +</tbody></table> + +В примере выше используется `log.Fatal`, но рекомендация также применима к +`os.Exit` или любому библиотечному коду, который вызывает `os.Exit`. + +```go +func main() { + if err := run(); err != nil { + fmt.Fprintln(os.Stderr, err) + os.Exit(1) + } +} +``` + +Вы можете изменить сигнатуру `run()`, чтобы она соответствовала вашим +потребностям. Например, если ваша программа должна завершаться с определёнными +кодами выхода при сбоях, `run()` может возвращать код выхода вместо ошибки. Это +позволяет модульным тестам также напрямую проверять это поведение. + +```go +func main() { + os.Exit(run(args)) +} + +func run() (exitCode int) { + // ... +} +``` + +Более общо, обратите внимание, что функция `run()`, используемая в этих +примерах, не является предписывающей. Существует гибкость в имени, сигнатуре и +настройке функции `run()`. Среди прочего, вы можете: + +- принимать неразобранные аргументы командной строки (например, + `run(os.Args[1:])`) +- разбирать аргументы командной строки в `main()` и передавать их в `run` +- использовать пользовательский тип ошибки для передачи кода выхода обратно в + `main()` +- помещать бизнес-логику на другой уровень абстракции, отличный от `package +main` + +Эта рекомендация требует только, чтобы в вашем `main()` было единственное место, +ответственное за фактическое завершение процесса. + +### Используйте теги полей в структурах для сериализации + +Любое поле структуры, которое сериализуется в JSON, YAML или другие форматы, +поддерживающие именование полей на основе тегов, должно быть аннотировано +соответствующим тегом. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +type Stock struct { + Price int + Name string +} + +bytes, err := json.Marshal(Stock{ + Price: 137, + Name: "UBER", +}) +``` + +</td><td> + +```go +type Stock struct { + Price int `json:"price"` + Name string `json:"name"` + // Безопасно переименовать Name в Symbol. +} + +bytes, err := json.Marshal(Stock{ + Price: 137, + Name: "UBER", +}) +``` + +</td></tr> +</tbody></table> + +Обоснование: Сериализованная форма структуры — это контракт между различными +системами. Изменения в структуре сериализованной формы — включая имена полей — +нарушают этот контракт. Указание имён полей внутри тегов делает контракт явным и +защищает от случайного его нарушения при рефакторинге или переименовании полей. + +### Не запускайте горутины по принципу «запустил и забыл» + +Горутины легковесны, но не бесплатны: как минимум, они требуют памяти для своего +стека и процессорного времени для планирования. Хотя эти затраты малы для +типичного использования горутин, они могут вызвать значительные проблемы с +производительностью, если горутины создаются в больших количествах без +контролируемого времени жизни. Горутины с неуправляемым временем жизни также +могут вызывать другие проблемы, например, мешать сборке мусора для +неиспользуемых объектов и удерживать ресурсы, которые в противном случае больше +не используются. + +Поэтому не допускайте утечек горутин в production коде. Используйте +[go.uber.org/goleak](https://pkg.go.dev/go.uber.org/goleak) для тестирования +утечек горутин внутри пакетов, которые могут их создавать. + +В общем случае каждая горутина: + +- должна иметь предсказуемый момент, когда она перестанет выполняться; или +- должен быть способ сигнализировать горутине, что ей следует остановиться + +В обоих случаях должен быть способ заблокировать выполнение и дождаться +завершения горутины. + +Например: + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +go func() { + for { + flush() + time.Sleep(delay) + } +}() +``` + +</td><td> + +```go +var ( + stop = make(chan struct{}) // сигнализирует горутине остановиться + done = make(chan struct{}) // сигнализирует нам, что горутина завершилась +) +go func() { + defer close(done) + + ticker := time.NewTicker(delay) + defer ticker.Stop() + for { + select { + case <-ticker.C: + flush() + case <-stop: + return + } + } +}() + +// В другом месте... +close(stop) // сигнализировать горутине остановиться +<-done // и ждать её завершения +``` + +</td></tr> +<tr><td> + +Нет способа остановить эту горутину. Она будет работать, пока приложение не +завершится. + +</td><td> + +Эту горутину можно остановить с помощью `close(stop)`, и мы можем дождаться её +завершения с помощью `<-done`. + +</td></tr> +</tbody></table> + +#### Дожидайтесь завершения горутин + +Для горутины, созданной системой, должен быть способ дождаться её завершения. +Есть два популярных способа сделать это: + +- Используйте `sync.WaitGroup`, чтобы дождаться завершения нескольких горутин. + Делайте так, если нужно ждать несколько горутин. + + ```go + var wg sync.WaitGroup + for i := 0; i < N; i++ { + wg.Go(...) + } + + // Чтобы дождаться завершения всех: + wg.Wait() + ``` + +- Добавьте ещё один `chan struct{}`, который горутина закроет по завершении. + Делайте так, если есть только одна горутина. + + ```go + done := make(chan struct{}) + go func() { + defer close(done) + // ... + }() + + // Чтобы дождаться завершения горутины: + <-done + ``` + +#### Не используйте горутины в `init()` + +Функции `init()` не должны запускать горутины. См. также [Избегайте +init()](#избегайте-init). + +Если пакету нужна фоновая горутина, он должен предоставлять объект, +ответственный за управление временем жизни горутины. Этот объект должен +предоставлять метод (`Close`, `Stop`, `Shutdown` и т.д.), который сигнализирует +фоновой горутине об остановке и ждёт её завершения. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +func init() { + go doWork() +} + +func doWork() { + for { + // ... + } +} +``` + +</td><td> + +```go +type Worker struct{ /* ... */ } + +func NewWorker(...) *Worker { + w := &Worker{ + stop: make(chan struct{}), + done: make(chan struct{}), + // ... + } + go w.doWork() +} + +func (w *Worker) doWork() { + defer close(w.done) + for { + // ... + case <-w.stop: + return + } +} + +// Shutdown говорит воркеру остановиться и ждёт, пока он завершится. +func (w *Worker) Shutdown() { + close(w.stop) + <-w.done +} +``` + +</td></tr> +<tr><td> + +Создаёт фоновую горутину безусловно при экспорте этого пакета пользователем. +Пользователь не имеет контроля над горутиной или способа её остановки. + +</td><td> + +Создаёт воркера только если пользователь его запрашивает. Предоставляет способ +остановки воркера, чтобы пользователь мог освободить используемые им ресурсы. + +Обратите внимание, что следует использовать `WaitGroup`, если воркер управляет +несколькими горутинами. См. [Дожидайтесь завершения +горутин](#дожидайтесь-завершения-горутин). + +</td></tr> +</tbody></table> + +## Производительность + +Рекомендации, специфичные для производительности, применяются только к «горячему +пути» (hot path). + +### Предпочитайте strconv вместо fmt + +При преобразовании примитивов в строки и обратно `strconv` быстрее, чем `fmt`. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +for i := 0; i < b.N; i++ { + s := fmt.Sprint(rand.Int()) +} +``` + +</td><td> + +```go +for i := 0; i < b.N; i++ { + s := strconv.Itoa(rand.Int()) +} +``` + +</td></tr> +<tr><td> + +```plain +BenchmarkFmtSprint-4 143 ns/op 2 allocs/op +``` + +</td><td> + +```plain +BenchmarkStrconv-4 64.2 ns/op 1 allocs/op +``` + +</td></tr> +</tbody></table> + +### Избегайте повторного преобразования строк в байты + +Не создавайте срезы байт из фиксированной строки повторно. Вместо этого +выполните преобразование один раз и сохраните результат. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +for i := 0; i < b.N; i++ { + w.Write([]byte("Hello world")) +} +``` + +</td><td> + +```go +data := []byte("Hello world") +for i := 0; i < b.N; i++ { + w.Write(data) +} +``` + +</td></tr> +<tr><td> + +```plain +BenchmarkBad-4 50000000 22.2 ns/op +``` + +</td><td> + +```plain +BenchmarkGood-4 500000000 3.25 ns/op +``` + +</td></tr> +</tbody></table> + +### Предпочитайте указание ёмкости контейнеров + +По возможности указывайте ёмкость контейнеров, чтобы выделить память для +контейнера заранее. Это минимизирует последующие выделения памяти (из-за +копирования и изменения размера контейнера) при добавлении элементов. + +#### Указание подсказки ёмкости для карт + +По возможности предоставляйте подсказку ёмкости при инициализации карт с помощью +`make()`. + +```go +make(map[T1]T2, hint) +``` + +Предоставление подсказки ёмкости для `make()` пытается правильно определить +размер карты при инициализации, что уменьшает необходимость её роста и выделений +памяти при добавлении элементов. + +Обратите внимание, что в отличие от срезов, подсказки ёмкости для карт не +гарантируют полного, упреждающего выделения, а используются для приблизительного +определения количества необходимых корзин хэш-карты. Следовательно, выделения +памяти всё ещё могут происходить при добавлении элементов в карту, даже до +указанной ёмкости. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +m := make(map[string]os.FileInfo) + +files, _ := os.ReadDir("./files") +for _, f := range files { + m[f.Name()] = f +} +``` + +</td><td> + +```go + +files, _ := os.ReadDir("./files") + +m := make(map[string]os.DirEntry, len(files)) +for _, f := range files { + m[f.Name()] = f +} +``` + +</td></tr> +<tr><td> + +`m` создаётся без подсказки размера; при присваивании может быть больше +выделений памяти. + +</td><td> + +`m` создаётся с подсказкой размера; при присваивании может быть меньше выделений +памяти. + +</td></tr> +</tbody></table> + +#### Указание ёмкости срезов + +По возможности предоставляйте подсказку ёмкости при инициализации срезов с +помощью `make()`, особенно при использовании `append`. + +```go +make([]T, length, capacity) +``` + +В отличие от карт, ёмкость среза — это не подсказка: компилятор выделит +достаточно памяти для ёмкости среза, предоставленной в `make()`, что означает, +что последующие операции `append()` не будут приводить к выделениям памяти (пока +длина среза не совпадёт с ёмкостью, после чего любые добавления потребуют +изменения размера для хранения дополнительных элементов). + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +for n := 0; n < b.N; n++ { + data := make([]int, 0) + for k := 0; k < size; k++{ + data = append(data, k) + } +} +``` + +</td><td> + +```go +for n := 0; n < b.N; n++ { + data := make([]int, 0, size) + for k := 0; k < size; k++{ + data = append(data, k) + } +} +``` + +</td></tr> +<tr><td> + +```plain +BenchmarkBad-4 100000000 2.48s +``` + +</td><td> + +```plain +BenchmarkGood-4 100000000 0.21s +``` + +</td></tr> +</tbody></table> + +## Стиль + +### Избегайте слишком длинных строк + +Избегайте строк кода, которые заставляют читателей прокручивать по горизонтали +или слишком сильно поворачивать голову. + +Мы рекомендуем мягкое ограничение длины строки в **99 символов**. Авторы должны +стараться переносить строки до достижения этого предела, но это не строгое +ограничение. Коду разрешено превышать этот лимит. + +### Будьте последовательны + +Некоторые рекомендации, изложенные в этом документе, можно оценить объективно; +другие ситуативны, контекстны или субъективны. + +Прежде всего, **будьте последовательны**. + +Последовательный код легче поддерживать, легче осмыслить, требует меньше +когнитивных усилий и легче переносить или обновлять по мере появления новых +соглашений или исправления классов ошибок. + +И наоборот, наличие множества различных или конфликтующих стилей в одной кодовой +базе создаёт накладные расходы на поддержку, неопределённость и когнитивный +диссонанс, что напрямую может способствовать снижению скорости разработки, +болезненным код-ревью и ошибкам. + +При применении этих рекомендаций к кодовой базе рекомендуется вносить изменения +на уровне пакета (или выше): применение на уровне подпакета нарушает указанную +выше проблему, внося несколько стилей в один код. + +### Группируйте схожие объявления + +Go поддерживает группировку схожих объявлений. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +import "a" +import "b" +``` + +</td><td> + +```go +import ( + "a" + "b" +) +``` + +</td></tr> +</tbody></table> + +Это также относится к константам, переменным и объявлениям типов. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go + +const a = 1 +const b = 2 + + + +var a = 1 +var b = 2 + + + +type Area float64 +type Volume float64 +``` + +</td><td> + +```go +const ( + a = 1 + b = 2 +) + +var ( + a = 1 + b = 2 +) + +type ( + Area float64 + Volume float64 +) +``` + +</td></tr> +</tbody></table> + +Группируйте только связанные объявления. Не группируйте несвязанные объявления. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +type Operation int + +const ( + Add Operation = iota + 1 + Subtract + Multiply + EnvVar = "MY_ENV" +) +``` + +</td><td> + +```go +type Operation int + +const ( + Add Operation = iota + 1 + Subtract + Multiply +) + +const EnvVar = "MY_ENV" +``` + +</td></tr> +</tbody></table> + +Группы не ограничены в том, где могут использоваться. Например, их можно +использовать внутри функций. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +func f() string { + red := color.New(0xff0000) + green := color.New(0x00ff00) + blue := color.New(0x0000ff) + + // ... +} +``` + +</td><td> + +```go +func f() string { + var ( + red = color.New(0xff0000) + green = color.New(0x00ff00) + blue = color.New(0x0000ff) + ) + + // ... +} +``` + +</td></tr> +</tbody></table> + +Исключение: Объявления переменных, особенно внутри функций, должны +группироваться вместе, если они объявлены рядом с другими переменными. Делайте +так для переменных, объявленных вместе, даже если они не связаны. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +func (c *client) request() { + caller := c.name + format := "json" + timeout := 5*time.Second + var err error + + // ... +} +``` + +</td><td> + +```go +func (c *client) request() { + var ( + caller = c.name + format = "json" + timeout = 5*time.Second + err error + ) + + // ... +} +``` + +</td></tr> +</tbody></table> + +### Порядок групп импорта + +Должно быть две группы импорта: + +- Стандартная библиотека +- Все остальные + +Это группировка, применяемая по умолчанию в `goimports`. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +import ( + "fmt" + "os" + "go.uber.org/atomic" + "golang.org/x/sync/errgroup" +) +``` + +</td><td> + +```go +import ( + "fmt" + "os" + + "go.uber.org/atomic" + "golang.org/x/sync/errgroup" +) +``` + +</td></tr> +</tbody></table> + +### Имена пакетов + +При именовании пакетов выбирайте имя, которое: + +- Состоит только из строчных букв. Без заглавных букв и подчёркиваний. +- Не требует переименования с использованием именованных импортов в большинстве + мест вызова. +- Короткое и ёмкое. Помните, что имя полностью указывается в каждом месте + вызова. +- Не во множественном числе. Например, `net/url`, а не `net/urls`. +- Не "common", "util", "shared" или "lib". Это плохие, неинформативные имена. + +См. также [Package Names](https://go.dev/blog/package-names) и [Style guideline +for Go packages](https://rakyll.org/style-packages/). + +### Имена функций + +Мы следуем соглашению сообщества Go об использовании [MixedCaps для имён +функций](https://go.dev/doc/effective_go#mixed-caps). Исключение делается для +тестовых функций, которые могут содержать подчёркивания для группировки +связанных тестовых случаев, например, `TestMyFunction_WhatIsBeingTested`. + +### Псевдонимы импорта + +Псевдонимы импорта должны использоваться, если имя пакета не совпадает с +последним элементом пути импорта. + +```go +import ( + "net/http" + + client "example.com/client-go" + trace "example.com/trace/v2" +) +``` + +Во всех остальных сценариях псевдонимы импорта следует избегать, если нет +прямого конфликта между импортами. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +import ( + "fmt" + "os" + runtimetrace "runtime/trace" + + nettrace "golang.net/x/trace" +) +``` + +</td><td> + +```go +import ( + "fmt" + "os" + "runtime/trace" + + nettrace "golang.net/x/trace" +) +``` + +</td></tr> +</tbody></table> + +### Группировка и порядок функций + +- Функции должны быть отсортированы в приблизительном порядке вызовов. +- Функции в файле должны быть сгруппированы по получателю. + +Следовательно, экспортируемые функции должны появляться первыми в файле после +определений `struct`, `const`, `var`. + +`newXYZ()`/`NewXYZ()` может появиться после определения типа, но до остальных +методов получателя. + +Поскольку функции группируются по получателю, простые вспомогательные функции +должны появляться ближе к концу файла. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +func (s *something) Cost() { + return calcCost(s.weights) +} + +type something struct{ ... } + +func calcCost(n []int) int {...} + +func (s *something) Stop() {...} + +func newSomething() *something { + return &something{} +} +``` + +</td><td> + +```go +type something struct{ ... } + +func newSomething() *something { + return &something{} +} + +func (s *something) Cost() { + return calcCost(s.weights) +} + +func (s *something) Stop() {...} + +func calcCost(n []int) int {...} +``` + +</td></tr> +</tbody></table> + +### Уменьшайте вложенность + +Код должен уменьшать вложенность, где это возможно, обрабатывая случаи +ошибок/особые условия первыми и возвращаясь рано или продолжая цикл. Уменьшайте +количество кода, вложенного на несколько уровней. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +for _, v := range data { + if v.F1 == 1 { + v = process(v) + if err := v.Call(); err == nil { + v.Send() + } else { + return err + } + } else { + log.Printf("Invalid v: %v", v) + } +} +``` + +</td><td> + +```go +for _, v := range data { + if v.F1 != 1 { + log.Printf("Invalid v: %v", v) + continue + } + + v = process(v) + if err := v.Call(); err != nil { + return err + } + v.Send() +} +``` + +</td></tr> +</tbody></table> + +### Избыточный Else + +Если переменная устанавливается в обеих ветках if, это можно заменить одним if. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +var a int +if b { + a = 100 +} else { + a = 10 +} +``` + +</td><td> + +```go +a := 10 +if b { + a = 100 +} +``` + +</td></tr> +</tbody></table> + +### Объявления переменных верхнего уровня + +На верхнем уровне используйте стандартное ключевое слово `var`. Не указывайте +тип, если он не отличается от типа выражения. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +var _s string = F() + +func F() string { return "A" } +``` + +</td><td> + +```go +var _s = F() +// Поскольку F уже указывает, что возвращает строку, нам не нужно снова указывать тип. + +func F() string { return "A" } +``` + +</td></tr> +</tbody></table> + +Указывайте тип, если тип выражения не совпадает точно с желаемым типом. + +```go +type myError struct{} + +func (myError) Error() string { return "error" } + +func F() myError { return myError{} } + +var _e error = F() +// F возвращает объект типа myError, но мы хотим error. +``` + +### Префикс \_ для неэкспортируемых глобальных переменных + +Добавляйте префикс `_` к неэкспортируемым переменным и константам верхнего +уровня, чтобы было ясно, что они являются глобальными символами, когда они +используются. + +Обоснование: Переменные и константы верхнего уровня имеют область видимости +пакета. Использование общего имени делает лёгким случайное использование +неправильного значения в другом файле. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +// foo.go + +const ( + defaultPort = 8080 + defaultUser = "user" +) + +// bar.go + +func Bar() { + defaultPort := 9090 + ... + fmt.Println("Default port", defaultPort) + + // Мы не увидим ошибку компиляции, если первая строка Bar() будет удалена. +} +``` + +</td><td> + +```go +// foo.go + +const ( + _defaultPort = 8080 + _defaultUser = "user" +) +``` + +</td></tr> +</tbody></table> + +**Исключение**: Неэкспортируемые значения ошибок могут использовать префикс +`err` без подчёркивания. См. [Именование ошибок](#именование-ошибок). + +### Встраивание в структурах + +Встроенные типы должны находиться в начале списка полей структуры, и должна быть +пустая строка, отделяющая встроенные поля от обычных полей. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +type Client struct { + version int + http.Client +} +``` + +</td><td> + +```go +type Client struct { + http.Client + + version int +} +``` + +</td></tr> +</tbody></table> + +Встраивание должно обеспечивать ощутимую пользу, например, добавлять или +расширять функциональность семантически-уместным способом. Оно должно делать это +без каких-либо негативных последствий для пользователя (см. также: [Избегайте +встраивания типов в публичные +структуры](#избегайте-встраивания-типов-в-публичные-структуры)). + +Исключение: Мьютексы не должны встраиваться, даже в неэкспортируемые типы. См. +также: [Нулевые значения мьютексов +допустимы](#нулевые-значения-мьютексов-допустимы). + +Встраивание **НЕ должно**: + +- Быть чисто косметическим или ориентированным на удобство. +- Усложнять создание или использование внешних типов. +- Влиять на нулевые значения внешних типов. Если внешний тип имеет полезное + нулевое значение, он должен сохранять его после встраивания внутреннего типа. +- Раскрывать несвязанные функции или поля внешнего типа как побочный эффект + встраивания внутреннего типа. +- Раскрывать неэкспортируемые типы. +- Влиять на семантику копирования внешних типов. +- Менять API или семантику типов внешних типов. +- Встраивать неканоническую форму внутреннего типа. +- Раскрывать детали реализации внешнего типа. +- Позволять пользователям наблюдать или контролировать внутренности типа. +- Менять общее поведение внутренних функций через обёртывание таким образом, + который может удивить пользователей. + +Проще говоря, встраивайте осознанно и преднамеренно. Хороший тест: "все ли эти +экспортируемые внутренние методы/поля были бы добавлены напрямую к внешнему +типу"; если ответ "некоторые" или "нет", не встраивайте внутренний тип — +используйте поле. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +type A struct { + // Плохо: A.Lock() и A.Unlock() теперь доступны, не предоставляют функциональной пользы и позволяют пользователям контролировать детали внутренностей A. + sync.Mutex +} +``` + +</td><td> + +```go +type countingWriteCloser struct { + // Хорошо: Write() предоставлен на этом внешнем уровне для конкретной цели и делегирует работу Write() внутреннего типа. + io.WriteCloser + + count int +} + +func (w *countingWriteCloser) Write(bs []byte) (int, error) { + w.count += len(bs) + return w.WriteCloser.Write(bs) +} +``` + +</td></tr> +<tr><td> + +```go +type Book struct { + // Плохо: указатель меняет полезность нулевого значения + io.ReadWriter + + // другие поля +} + +// позже +var b Book +b.Read(...) // panic: nil pointer +b.String() // panic: nil pointer +b.Write(...) // panic: nil pointer +``` + +</td><td> + +```go +type Book struct { + // Хорошо: имеет полезное нулевое значение + bytes.Buffer + + // другие поля +} + +// позже + +var b Book +b.Read(...) // ok +b.String() // ok +b.Write(...) // ok +``` + +</td></tr> +<tr><td> + +```go +type Client struct { + sync.Mutex + sync.WaitGroup + bytes.Buffer + url.URL +} +``` + +</td><td> + +```go +type Client struct { + mtx sync.Mutex + wg sync.WaitGroup + buf bytes.Buffer + url url.URL +} +``` + +</td></tr> +</tbody></table> + +### Объявление локальных переменных + +Короткое объявление переменных (`:=`) должно использоваться, если переменная +явно устанавливается в некоторое значение. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +var s = "foo" +``` + +</td><td> + +```go +s := "foo" +``` + +</td></tr> +</tbody></table> + +Однако бывают случаи, когда значение по умолчанию понятнее при использовании +ключевого слова `var`. [Объявление пустых +срезов](https://go.dev/wiki/CodeReviewComments#declaring-empty-slices), +например. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +func f(list []int) { + filtered := []int{} + for _, v := range list { + if v > 10 { + filtered = append(filtered, v) + } + } +} +``` + +</td><td> + +```go +func f(list []int) { + var filtered []int + for _, v := range list { + if v > 10 { + filtered = append(filtered, v) + } + } +} +``` + +</td></tr> +</tbody></table> + +### nil — это валидный срез + +`nil` — это валидный срез длины 0. Это означает, что: + +- Не следует явно возвращать срез длины ноль. Возвращайте `nil` вместо этого. + + <table> + <thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> + <tbody> + <tr><td> + + ```go + if x == "" { + return []int{} + } + ``` + + </td><td> + + ```go + if x == "" { + return nil + } + ``` + + </td></tr> + </tbody></table> + +- Чтобы проверить, пуст ли срез, всегда используйте `len(s) == 0`. Не проверяйте + на `nil`. + + <table> + <thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> + <tbody> + <tr><td> + + ```go + func isEmpty(s []string) bool { + return s == nil + } + ``` + + </td><td> + + ```go + func isEmpty(s []string) bool { + return len(s) == 0 + } + ``` + + </td></tr> + </tbody></table> + +- Нулевое значение (срез, объявленный с `var`) можно использовать сразу без +`make()`. + + <table> + <thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> + <tbody> + <tr><td> + +```go +nums := []int{} +// или, nums := make([]int) + +if add1 { + nums = append(nums, 1) +} + +if add2 { + nums = append(nums, 2) +} +``` + +</td><td> + +```go +var nums []int + +if add1 { + nums = append(nums, 1) +} + +if add2 { + nums = append(nums, 2) +} +``` + +</td></tr> +</tbody></table> + +Помните, что хотя nil-срез является валидным срезом, он не эквивалентен +выделенному срезу длины 0 — один является nil, а другой нет — и они могут +обрабатываться по-разному в разных ситуациях (например, при сериализации). + +### Уменьшайте область видимости переменных + +По возможности уменьшайте область видимости переменных и констант. Не уменьшайте +область видимости, если это противоречит [Уменьшению +вложенности](#уменьшайте-вложенность). + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +err := os.WriteFile(name, data, 0644) +if err != nil { + return err +} +``` + +</td><td> + +```go +if err := os.WriteFile(name, data, 0644); err != nil { + return err +} +``` + +</td></tr> +</tbody></table> + +Если вам нужен результат вызова функции вне if, то не следует пытаться уменьшить +область видимости. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +if data, err := os.ReadFile(name); err == nil { + err = cfg.Decode(data) + if err != nil { + return err + } + + fmt.Println(cfg) + return nil +} else { + return err +} +``` + +</td><td> + +```go +data, err := os.ReadFile(name) +if err != nil { + return err +} + +if err := cfg.Decode(data); err != nil { + return err +} + +fmt.Println(cfg) +return nil +``` + +</td></tr> +</tbody></table> + +Константам не нужно быть глобальными, если они не используются в нескольких +функциях или файлах или являются частью внешнего контракта пакета. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +const ( + _defaultPort = 8080 + _defaultUser = "user" +) + +func Bar() { + fmt.Println("Default port", _defaultPort) +} +``` + +</td><td> + +```go +func Bar() { + const ( + defaultPort = 8080 + defaultUser = "user" + ) + fmt.Println("Default port", defaultPort) +} +``` + +</td></tr> +</tbody></table> + +### Избегайте «голых» параметров + +«Голые» параметры в вызовах функций могут ухудшать читаемость. Добавляйте +комментарии в стиле C (`/* ... */`) для имён параметров, когда их значение +неочевидно. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +// func printInfo(name string, isLocal, done bool) + +printInfo("foo", true, true) +``` + +</td><td> + +```go +// func printInfo(name string, isLocal, done bool) + +printInfo("foo", true /* isLocal */, true /* done */) +``` + +</td></tr> +</tbody></table> + +Ещё лучше заменить «голые» типы `bool` пользовательскими типами для более +читаемого и типобезопасного кода. Это позволяет в будущем иметь более двух +состояний (true/false) для этого параметра. + +```go +type Region int + +const ( + UnknownRegion Region = iota + Local +) + +type Status int + +const ( + StatusReady Status = iota + 1 + StatusDone + // Возможно, в будущем у нас будет StatusInProgress. +) + +func printInfo(name string, region Region, status Status) +``` + +### Используйте сырые строковые литералы, чтобы избежать экранирования + +Go поддерживает [сырые строковые +литералы](https://go.dev/ref/spec#raw_string_lit), которые могут занимать +несколько строк и включать кавычки. Используйте их, чтобы избежать ручного +экранирования строк, которое гораздо труднее читать. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +wantError := "unknown name:\"test\"" +``` + +</td><td> + +```go +wantError := `unknown error:"test"` +``` + +</td></tr> +</tbody></table> + +### Инициализация структур + +#### Используйте имена полей для инициализации структур + +Вы почти всегда должны указывать имена полей при инициализации структур. Теперь +это обеспечивается [`go vet`](https://pkg.go.dev/cmd/vet). + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +k := User{"John", "Doe", true} +``` + +</td><td> + +```go +k := User{ + FirstName: "John", + LastName: "Doe", + Admin: true, +} +``` + +</td></tr> +</tbody></table> + +Исключение: Имена полей _могут_ быть опущены в таблицах тестов, когда полей 3 +или меньше. + +```go +tests := []struct{ + op Operation + want string +}{ + {Add, "add"}, + {Subtract, "subtract"}, +} +``` + +#### Опускайте поля с нулевыми значениями в структурах + +При инициализации структур с именами полей опускайте поля, имеющие нулевые +значения, если они не предоставляют значимый контекст. В противном случае +позвольте Go автоматически установить их в нулевые значения. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +user := User{ + FirstName: "John", + LastName: "Doe", + MiddleName: "", + Admin: false, +} +``` + +</td><td> + +```go +user := User{ + FirstName: "John", + LastName: "Doe", +} +``` + +</td></tr> +</tbody></table> + +Это помогает уменьшить шум для читателей, опуская значения, которые являются +стандартными в данном контексте. Указываются только значимые значения. + +Включайте нулевые значения, когда имена полей предоставляют значимый контекст. +Например, тестовые случаи в [Табличных тестах](#табличные-тесты) могут выиграть +от указания имён полей, даже когда они имеют нулевые значения. + +```go +tests := []struct{ + give string + want int +}{ + {give: "0", want: 0}, + // ... +} +``` + +#### Используйте `var` для структур с нулевыми значениями + +Когда все поля структуры опущены в объявлении, используйте форму `var` для +объявления структуры. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +user := User{} +``` + +</td><td> + +```go +var user User +``` + +</td></tr> +</tbody></table> + +Это отличает структуры с нулевыми значениями от тех, у которых есть ненулевые +поля, аналогично различию, создаваемому для [инициализации +карт](#инициализация-карт), и соответствует тому, как мы предпочитаем [объявлять +пустые срезы](https://go.dev/wiki/CodeReviewComments#declaring-empty-slices). + +#### Инициализация ссылок на структуры + +Используйте `&T{}` вместо `new(T)` при инициализации ссылок на структуры, чтобы +это было согласовано с инициализацией структур. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +sval := T{Name: "foo"} + +// несогласованно +sptr := new(T) +sptr.Name = "bar" +``` + +</td><td> + +```go +sval := T{Name: "foo"} + +sptr := &T{Name: "bar"} +``` + +</td></tr> +</tbody></table> + +### Инициализация карт + +Предпочитайте `make(..)` для пустых карт и карт, заполняемых программно. Это +делает инициализацию карт визуально отличной от объявления и позволяет легко +добавить подсказку размера позже, если она доступна. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +var ( + // m1 безопасна для чтения и записи; + // m2 вызовет панику при записи. + m1 = map[T1]T2{} + m2 map[T1]T2 +) +``` + +</td><td> + +```go +var ( + // m1 безопасна для чтения и записи; + // m2 вызовет панику при записи. + m1 = make(map[T1]T2) + m2 map[T1]T2 +) +``` + +</td></tr> +<tr><td> + +Объявление и инициализация визуально похожи. + +</td><td> + +Объявление и инициализация визуально различны. + +</td></tr> +</tbody></table> + +По возможности предоставляйте подсказку ёмкости при инициализации карт с помощью +`make()`. См. [Указание подсказки ёмкости для +карт](#указание-подсказки-ёмкости-для-карт) для получения дополнительной +информации. + +С другой стороны, если карта содержит фиксированный список элементов, +используйте литералы карт для её инициализации. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +m := make(map[T1]T2, 3) +m[k1] = v1 +m[k2] = v2 +m[k3] = v3 +``` + +</td><td> + +```go +m := map[T1]T2{ + k1: v1, + k2: v2, + k3: v3, +} +``` + +</td></tr> +</tbody></table> + +Основное правило — использовать литералы карт при добавлении фиксированного +набора элементов во время инициализации, в противном случае используйте `make` +(и указывайте подсказку размера, если доступна). + +### Строки формата вне Printf + +Если вы объявляете строки формата для функций в стиле `Printf` вне строкового +литерала, сделайте их значениями `const`. + +Это помогает `go vet` выполнять статический анализ строки формата. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +msg := "unexpected values %v, %v\n" +fmt.Printf(msg, 1, 2) +``` + +</td><td> + +```go +const msg = "unexpected values %v, %v\n" +fmt.Printf(msg, 1, 2) +``` + +</td></tr> +</tbody></table> + +### Именование функций в стиле Printf + +Когда вы объявляете функцию в стиле `Printf`, убедитесь, что `go vet` может её +обнаружить и проверить строку формата. + +Это означает, что следует использовать предопределённые имена функций в стиле +`Printf`, если это возможно. `go vet` проверяет их по умолчанию. См. [Printf +family](https://pkg.go.dev/cmd/vet#hdr-Printf_family) для получения +дополнительной информации. + +Если использование предопределённых имён невозможно, заканчивайте выбранное вами +имя на f: `Wrapf`, а не `Wrap`. `go vet` можно попросить проверять определённые +имена в стиле `Printf`, но они должны заканчиваться на f. + +```shell +go vet -printfuncs=wrapf,statusf +``` + +См. также [go vet: Printf family +check](https://kuzminva.wordpress.com/2017/11/07/go-vet-printf-family-check/). + +## Паттерны + +### Табличные тесты + +Табличные тесты с [подтестами](https://go.dev/blog/subtests) могут быть полезным +паттерном для написания тестов, чтобы избежать дублирования кода, когда основная +тестовая логика повторяется. + +Если тестируемую систему нужно проверить на соответствие _нескольким условиям_, +где определённые части входных и выходных данных меняются, следует использовать +табличные тесты, чтобы уменьшить избыточность и улучшить читаемость. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +// func TestSplitHostPort(t *testing.T) + +host, port, err := net.SplitHostPort("192.0.2.0:8000") +require.NoError(t, err) +assert.Equal(t, "192.0.2.0", host) +assert.Equal(t, "8000", port) + +host, port, err = net.SplitHostPort("192.0.2.0:http") +require.NoError(t, err) +assert.Equal(t, "192.0.2.0", host) +assert.Equal(t, "http", port) + +host, port, err = net.SplitHostPort(":8000") +require.NoError(t, err) +assert.Equal(t, "", host) +assert.Equal(t, "8000", port) + +host, port, err = net.SplitHostPort("1:8") +require.NoError(t, err) +assert.Equal(t, "1", host) +assert.Equal(t, "8", port) +``` + +</td><td> + +```go +// func TestSplitHostPort(t *testing.T) + +tests := []struct{ + give string + wantHost string + wantPort string +}{ + { + give: "192.0.2.0:8000", + wantHost: "192.0.2.0", + wantPort: "8000", + }, + { + give: "192.0.2.0:http", + wantHost: "192.0.2.0", + wantPort: "http", + }, + { + give: ":8000", + wantHost: "", + wantPort: "8000", + }, + { + give: "1:8", + wantHost: "1", + wantPort: "8", + }, +} + +for _, tt := range tests { + t.Run(tt.give, func(t *testing.T) { + host, port, err := net.SplitHostPort(tt.give) + require.NoError(t, err) + assert.Equal(t, tt.wantHost, host) + assert.Equal(t, tt.wantPort, port) + }) +} +``` + +</td></tr> +</tbody></table> + +Табличные тесты облегчают добавление контекста к сообщениям об ошибках, +уменьшают дублирование логики и позволяют добавлять новые тестовые случаи. + +Мы следуем соглашению, что срез структур называется `tests`, а каждый тестовый +случай — `tt`. Кроме того, мы рекомендуем явно указывать входные и выходные +значения для каждого тестового случая с префиксами `give` и `want`. + +```go +tests := []struct{ + give string + wantHost string + wantPort string +}{ + // ... +} + +for _, tt := range tests { + // ... +} +``` + +#### Избегайте излишней сложности в табличных тестах + +Табличные тесты могут быть трудны для чтения и поддержки, если подтесты содержат +условные проверки или другую разветвлённую логику. Табличные тесты **НЕ ДОЛЖНЫ** +использоваться всякий раз, когда внутри подтестов требуется сложная или условная +логика (т.е. сложная логика внутри цикла `for`). + +Большие, сложные табличные тесты ухудшают читаемость и поддерживаемость, потому +что читателям тестов может быть трудно отлаживать возникающие сбои тестов. + +Такие табличные тесты следует разделить либо на несколько таблиц тестов, либо на +несколько отдельных функций `Test...`. + +К некоторым идеалам, к которым стоит стремиться, относятся: + +- Фокусировка на самой узкой единице поведения +- Минимизация «глубины теста» и избегание условных проверок (см. ниже) +- Обеспечение того, что все поля таблицы используются во всех тестах +- Обеспечение того, что вся тестовая логика выполняется для всех случаев таблицы + +В этом контексте «глубина теста» означает «внутри данного теста, количество +последовательных проверок, требующих выполнения предыдущих проверок» (аналогично +цикломатической сложности). Наличие «более мелких» тестов означает меньше связей +между проверками и, что более важно, что эти проверки по умолчанию менее +вероятно будут условными. + +Конкретно, табличные тесты могут стать запутанными и трудными для чтения, если +они используют несколько ветвящихся путей (например, `shouldError`, `expectCall` +и т.д.), используют много операторов `if` для специфичных ожиданий моков +(например, `shouldCallFoo`) или размещают функции внутри таблицы (например, +`setupMocks func(*FooMock)`). + +Однако при тестировании поведения, которое меняется только в зависимости от +изменённых входных данных, может быть предпочтительнее группировать схожие +случаи вместе в табличном тесте, чтобы лучше иллюстрировать, как поведение +меняется при всех входных данных, а не разделять иначе сопоставимые единицы на +отдельные тесты и делать их более трудными для сравнения и противопоставления. + +Если тело теста короткое и простое, допустимо иметь единственный ветвящийся путь +для случаев успеха и неудачи с полем таблицы типа `shouldErr` для указания +ожиданий ошибки. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +func TestComplicatedTable(t *testing.T) { + tests := []struct { + give string + want string + wantErr error + shouldCallX bool + shouldCallY bool + giveXResponse string + giveXErr error + giveYResponse string + giveYErr error + }{ + // ... + } + + for _, tt := range tests { + t.Run(tt.give, func(t *testing.T) { + // настройка моков + ctrl := gomock.NewController(t) + xMock := xmock.NewMockX(ctrl) + if tt.shouldCallX { + xMock.EXPECT().Call().Return( + tt.giveXResponse, tt.giveXErr, + ) + } + yMock := ymock.NewMockY(ctrl) + if tt.shouldCallY { + yMock.EXPECT().Call().Return( + tt.giveYResponse, tt.giveYErr, + ) + } + + got, err := DoComplexThing(tt.give, xMock, yMock) + + // проверка результатов + if tt.wantErr != nil { + require.EqualError(t, err, tt.wantErr) + return + } + require.NoError(t, err) + assert.Equal(t, want, got) + }) + } +} +``` + +</td><td> + +```go +func TestShouldCallX(t *testing.T) { + // настройка моков + ctrl := gomock.NewController(t) + xMock := xmock.NewMockX(ctrl) + xMock.EXPECT().Call().Return("XResponse", nil) + + yMock := ymock.NewMockY(ctrl) + + got, err := DoComplexThing("inputX", xMock, yMock) + + require.NoError(t, err) + assert.Equal(t, "want", got) +} + +func TestShouldCallYAndFail(t *testing.T) { + // настройка моков + ctrl := gomock.NewController(t) + xMock := xmock.NewMockX(ctrl) + + yMock := ymock.NewMockY(ctrl) + yMock.EXPECT().Call().Return("YResponse", nil) + + _, err := DoComplexThing("inputY", xMock, yMock) + assert.EqualError(t, err, "Y failed") +} +``` + +</td></tr> +</tbody></table> + +Эта сложность делает тест более трудным для изменения, понимания и +доказательства его корректности. + +Хотя строгих правил нет, читаемость и поддерживаемость всегда должны быть +главными при выборе между табличными тестами и отдельными тестами для +множественных входов/выходов системы. + +#### Параллельные тесты + +Параллельные тесты, как и некоторые специализированные циклы (например, те, что +создают горутины или захватывают ссылки как часть тела цикла), должны заботиться +о явном присваивании переменных цикла внутри области видимости цикла, чтобы +гарантировать, что они содержат ожидаемые значения. + +```go +tests := []struct{ + give string + // ... +}{ + // ... +} + +for _, tt := range tests { + tt := tt // для t.Parallel + t.Run(tt.give, func(t *testing.T) { + t.Parallel() + // ... + }) +} +``` + +В примере выше мы должны объявить переменную `tt` с областью видимости итерации +цикла из-за использования `t.Parallel()` ниже. Если мы этого не сделаем, +большинство или все тесты получат неожиданное значение для `tt` или значение, +которое меняется во время их выполнения. + +<!-- TODO: Объяснить, как использовать _test пакеты. --> + +### Функциональные опции + +Функциональные опции — это паттерн, в котором вы объявляете непрозрачный тип +`Option`, который записывает информацию в некоторую внутреннюю структуру. Вы +принимаете переменное количество этих опций и действуете на основе полной +информации, записанной опциями во внутренней структуре. + +Используйте этот паттерн для необязательных аргументов в конструкторах и других +публичных API, которые, как вы предвидите, могут потребовать расширения, +особенно если у вас уже есть три или более аргументов в этих функциях. + +<table> +<thead><tr><th>Плохо</th><th>Хорошо</th></tr></thead> +<tbody> +<tr><td> + +```go +// package db + +func Open( + addr string, + cache bool, + logger *zap.Logger +) (*Connection, error) { + // ... +} +``` + +</td><td> + +```go +// package db + +type Option interface { + // ... +} + +func WithCache(c bool) Option { + // ... +} + +func WithLogger(log *zap.Logger) Option { + // ... +} + +// Open создаёт соединение. +func Open( + addr string, + opts ...Option, +) (*Connection, error) { + // ... +} +``` + +</td></tr> +<tr><td> + +Параметры cache и logger всегда должны предоставляться, даже если пользователь +хочет использовать значения по умолчанию. + +```go +db.Open(addr, db.DefaultCache, zap.NewNop()) +db.Open(addr, db.DefaultCache, log) +db.Open(addr, false /* cache */, zap.NewNop()) +db.Open(addr, false /* cache */, log) +``` + +</td><td> + +Опции предоставляются только при необходимости. + +```go +db.Open(addr) +db.Open(addr, db.WithLogger(log)) +db.Open(addr, db.WithCache(false)) +db.Open( + addr, + db.WithCache(false), + db.WithLogger(log), +) +``` + +</td></tr> +</tbody></table> + +Наш рекомендуемый способ реализации этого паттерна — использование интерфейса +`Option` с неэкспортируемым методом, записывающим опции в неэкспортируемую +структуру `options`. + +```go +type options struct { + cache bool + logger *zap.Logger +} + +type Option interface { + apply(*options) +} + +type cacheOption bool + +func (c cacheOption) apply(opts *options) { + opts.cache = bool(c) +} + +func WithCache(c bool) Option { + return cacheOption(c) +} + +type loggerOption struct { + Log *zap.Logger +} + +func (l loggerOption) apply(opts *options) { + opts.logger = l.Log +} + +func WithLogger(log *zap.Logger) Option { + return loggerOption{Log: log} +} + +// Open создаёт соединение. +func Open( + addr string, + opts ...Option, +) (*Connection, error) { + options := options{ + cache: defaultCache, + logger: zap.NewNop(), + } + + for _, o := range opts { + o.apply(&options) + } + + // ... +} +``` + +Обратите внимание, что существует метод реализации этого паттерна с +использованием замыканий, но мы считаем, что паттерн выше предоставляет больше +гибкости авторам и легче отлаживается и тестируется пользователями. В частности, +он позволяет сравнивать опции друг с другом в тестах и моках, в отличие от +замыканий, где это невозможно. Кроме того, он позволяет опциям реализовывать +другие интерфейсы, включая `fmt.Stringer`, что позволяет создавать удобочитаемые +строковые представления опций. + +См. также, + +- [Self-referential functions and the design of + options](https://commandcenter.blogspot.com/2014/01/self-referential-functions-and-design.html) +- [Functional options for friendly + APIs](https://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis) + +<!-- TODO: заменить это на структуры параметров и функциональные опции, когда использовать одно против другого --> + +## Линтинг + +Более важно, чем любой «благословленный» набор линтеров, — линтить +последовательно по всей кодовой базе. + +Мы рекомендуем использовать следующие линтеры как минимум, потому что считаем, +что они помогают выявить наиболее распространённые проблемы, а также +устанавливают высокую планку качества кода, не будучи излишне предписывающими: + +- [errcheck](https://github.com/kisielk/errcheck) для обеспечения обработки + ошибок +- [goimports](https://pkg.go.dev/golang.org/x/tools/cmd/goimports) для + форматирования кода и управления импортами +- [golint](https://github.com/golang/lint) для указания на распространённые + стилевые ошибки +- [govet](https://pkg.go.dev/cmd/vet) для анализа кода на распространённые + ошибки +- [staticcheck](https://staticcheck.dev) для выполнения различных проверок + статического анализа + +### Запускатели линтеров + +Мы рекомендуем [golangci-lint](https://github.com/golangci/golangci-lint) в +качестве основного запускателя линтеров для кода на Go, во многом благодаря его +производительности в больших кодовых базах и возможности настраивать и +использовать многие канонические линтеры одновременно. Этот репозиторий содержит +пример +[.golangci.yml](https://github.com/uber-go/guide/blob/master/.golangci.yml) +файла конфигурации с рекомендуемыми линтерами и настройками. + +golangci-lint имеет [различные +линтеры](https://golangci-lint.run/usage/linters/), доступные для использования. +Вышеуказанные линтеры рекомендуются в качестве базового набора, и мы поощряем +команды добавлять любые дополнительные линтеры, которые имеют смысл для их +проектов. diff --git a/content/pages/setup/_index.md b/content/pages/setup/_index.md new file mode 100644 index 0000000..92c00a3 --- /dev/null +++ b/content/pages/setup/_index.md @@ -0,0 +1,6 @@ +--- +order: 10 +title: Мой сетап 2025 +--- + +Пополняемый раздел с моим сетапом diff --git a/content/pages/setup/laptop.md b/content/pages/setup/laptop.md new file mode 100644 index 0000000..4aa14c9 --- /dev/null +++ b/content/pages/setup/laptop.md @@ -0,0 +1,36 @@ +--- +order: 20 +title: Ноутбук +--- + +Уже достаточно давно я сторонник исключительно ноутбуков и никак не воспринимаю +стационарные компьютеры. При этом, я считаю, что ноутбук должен быть +одновременно и мощным, мобильным и, что важно, ремонтопригодным, даже в домашних +условиях. Понимаю, что на практике это практически не осуществимо. Но самым +близким к этому для меня стал Lenovo Thinkpad T14 Gen4, версия на intel (это +важно, т.к. только intel версия поддерживает расширение ОЗУ). ОЗУ я в нем добил +до 48Гб, пока мне хватает. + +Вот основное что на нём установлено: + +- ОС: AltLinux p11. +- DE: Gnome 48 +- Эмулятор терминала: Ghostty. +- Оболочка: zsh. +- Текстовый редактор: Neovim/VSCodium +- Браузер: Яндекс Браузер. +- Коммуникации: Thunderbird/Neomutt (e-mail), Dino (jabber), telegram desktop + (будь он неладен). +- Музыка: Rhythmbox. +- Видео: VLC. +- Книги: лежат на NAS + сразу достаточно много загрузил в читалку. Была calibre, + но я так и не оценил от неё плюсов и дропнул. +- Основной язык: golang (удивительно). +- Синхронизация: с помощью syncthing синхронизирую ноутбук <-> NAS <-> смартфон + только одну директорию: Документы. По сути, не считая директории с исходниками + проектов, это моя самая важная директория на компьютере. +- Хранилище знаний: <del>[Obsidian](/posts/2024-11-17-obsidian/)</del> пока + присматриваюсь к ZK или к обычным текстовым файлам + +Это база, остальное не столько важно. + diff --git a/content/pages/setup/nas.md b/content/pages/setup/nas.md new file mode 100644 index 0000000..a3f3d25 --- /dev/null +++ b/content/pages/setup/nas.md @@ -0,0 +1,32 @@ +--- +order: 40 +title: NAS +--- + +Synology DS420+ + +Это, наверное, одно из лучших моих вложений денег. Мой личный суверенитет от +облаков. + +Основные функции: + +* Собственно, синхронизация той самой важной для меня директории «Документы». + Потому что её потерю я точно не смогу восполнить. +* Инкрементальный бекап ноутбука через rsync, как я где-то уже писал, вроде в + телеге (может стоит и здесь оставить заметку на всякий случай?). +* Календарь / контакты по webdav. Просто приятно. Хорошая альтернатива облакам. +* Торрентокачалка. Пиратство морально оправдано. Точка. +* Медиасервер. В основном чтобы просматривать трофейный контент на смарт тв. +* TT-RSS. Читаю RSS ленты на смартфоне и ноутбуке, а TT-RSS позволяет + синхронизировать уже прочитанное. + +Утерянный или недоделанный функционал: + +* Синхронизация подкастов по протоколу gpodder (AntennaPod на смартфоне и в + автомобиле + Kasts на ноутбуке). Раньше синкал через Nextcloud, отказался от + него. Пилю синхронизацию в свободное время. Когда допилю — расскажу в этом + блоге. +* Медиастримминг музыки с NAS на смартфон / компьютер / автомобиль. Пока не + дошли руки наладить. Обхожусь дедовскими способами — на каждом устройстве + просто локальная медиатека. + diff --git a/content/pages/setup/pda.md b/content/pages/setup/pda.md new file mode 100644 index 0000000..59aa33c --- /dev/null +++ b/content/pages/setup/pda.md @@ -0,0 +1,38 @@ +--- +order: 30 +title: Смартфон +--- +OnePlus 10T (рутованный) + +Бо́льшая часть гуглоговна удалена или отключена. В основном, стараюсь +использовать софт из F-Droid. + +В основном, стараюсь держать минимально необходимый набор софта — банковские +приложения, навигацию, коммуникационные приложения, читалки, да пару простеньких +игрушек для скрашивания досуга. + +Самое главное — по максимуму отключаю всевозможные уведомления. Ничего не должно +меня тревожить. Всё так же остаюсь сторонником идеи что пуши не нужны, а что-то +_действительно_ важное — и так придёт на e-mail. Единственное исключение — +jabber и рабочий мессенджер. Первый — это этакий бонус узкому элитарному кругу +пользователей джаббера, а второй — поскольку рабочие обязанности важнее моих +заморочек. + +Из интересного: + +* ntodotxt - тудушник, который отлично работает с Todo.txt. +* Conversations - jabber. +* syncthing - синхронизация. +* DAVx5 - приложение для синхронизации календарей и контактов с NAS. +* DS File, DS Get - приложения для работы с NAS. +* OSMand и OrganicMaps - оффлайн навигация. Ни раз выручала, когда онлайновый + карты приказывали долго жить без интернетов. +* AntennaPod - ИМХО лучшее приложение для подкастов. +* AIMP - замечательный аудио плеер для локальной музыки. +* VLC - отличный видеоплеер. +* KDE Connect - стоит исключительно для быстрого перебрасывания файлов на + компьютер. + +Вроде, из самого интересного — всё. Буду дописывать, если что ещё вспомню. + + |