diff options
Diffstat (limited to 'content/pages/gostyleguide/google/main.md')
| -rw-r--r-- | content/pages/gostyleguide/google/main.md | 184 |
1 files changed, 184 insertions, 0 deletions
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) |