diff options
Diffstat (limited to '')
| -rw-r--r-- | content/pages/gostyleguide/google/main.md | 184 |
1 files changed, 0 insertions, 184 deletions
diff --git a/content/pages/gostyleguide/google/main.md b/content/pages/gostyleguide/google/main.md deleted file mode 100644 index b3714ee..0000000 --- a/content/pages/gostyleguide/google/main.md +++ /dev/null @@ -1,184 +0,0 @@ ---- -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) |