1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
---
title: Google Go Style Guide
---
# Стиль Go
Оригинал: https://google.github.io/styleguide/go
<!--more-->
<!--more -->
Руководство по стилю Go и сопутствующие документы кодифицируют современные
наилучшие подходы к написанию читаемого и идиоматичного кода на Go. Следование
Руководству по стилю не является абсолютным требованием, и эти документы никогда
не будут исчерпывающими. Наша цель — минимизировать неопределённость при
написании читаемого кода на Go, чтобы новички в языке могли избежать
распространённых ошибок. Руководство по стилю также служит для унификации
рекомендаций по стилю, даваемых любым рецензентом кода Go в Google.
| Документ | [Нормативный] | [Канонический] |
| ----------------------------------------------------------------- | ------------- | -------------- |
| [**Руководство по стилю**](/pages/gostyleguide/google/guide/) | Да | Да |
| [**Решения по стилю**](/pages/gostyleguide/google/decisions/) | Да | Нет |
| [**Лучшие практики**](/pages/gostyleguide/google/best-practices/) | Нет | Нет |
[Нормативный]: #нормативный
[Канонический]: #канонический
<a id="docs"></a>
### Документы
1. **[Руководство по стилю](/pages/gostyleguide/google/guide)**
описывает основы стиля Go в Google. Этот документ является окончательным и
служит основой для рекомендаций в «Решениях по стилю» и «Лучших практиках».
1. **[Решения по стилю](/pages/gostyleguide/google/decisions)** —
это более подробный документ, который суммирует решения по конкретным
вопросам стиля и, где уместно, обсуждает обоснование этих решений.
Эти решения могут иногда меняться на основе новых данных, новых возможностей
языка, новых библиотек или возникающих паттернов, но не ожидается, что
отдельные программисты Go в Google должны следить за актуальностью этого
документа.
1. **[Лучшие практики](/pages/gostyleguide/google/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)
|
