Google Go Style Guide

Стиль Go

Оригинал: https://google.github.io/styleguide/go

Руководство по стилю Go и сопутствующие документы кодифицируют современные наилучшие подходы к написанию читаемого и идиоматичного кода на Go. Следование Руководству по стилю не является абсолютным требованием, и эти документы никогда не будут исчерпывающими. Наша цель — минимизировать неопределённость при написании читаемого кода на Go, чтобы новички в языке могли избежать распространённых ошибок. Руководство по стилю также служит для унификации рекомендаций по стилю, даваемых любым рецензентом кода Go в Google.

Документ	Нормативный	Канонический
Руководство по стилю	Да	Да
Решения по стилю	Да	Нет
Лучшие практики	Нет	Нет

Документы

Руководство по стилю описывает основы стиля Go в Google. Этот документ является окончательным и служит основой для рекомендаций в «Решениях по стилю» и «Лучших практиках».
Решения по стилю — это более подробный документ, который суммирует решения по конкретным вопросам стиля и, где уместно, обсуждает обоснование этих решений.

Эти решения могут иногда меняться на основе новых данных, новых возможностей языка, новых библиотек или возникающих паттернов, но не ожидается, что отдельные программисты Go в Google должны следить за актуальностью этого документа.
Лучшие практики документируют некоторые паттерны, которые развивались со временем для решения общих задач, хорошо читаются и устойчивы к потребностям поддержки кода.

Эти лучшие практики не являются каноническими, но программистам Go в Google рекомендуется использовать их там, где это возможно, для сохранения единообразия и согласованности кодовой базы.

Эти документы призваны:

Согласовать набор принципов для оценки альтернативных стилей
Кодифицировать устоявшиеся вопросы стиля Go
Документировать и предоставить канонические примеры идиом Go
Документировать плюсы и минусы различных решений по стилю
Помочь минимизировать неожиданности при рецензировании читаемости кода Go
Помочь наставникам по читаемости использовать согласованную терминологию и рекомендации

Эти документы не призваны:

Быть исчерпывающим списком замечаний, которые можно дать при рецензировании читаемости
Перечислять все правила, которые каждый должен помнить и всегда соблюдать
Заменять здравый смысл при использовании возможностей языка и стиля
Оправдывать масштабные изменения для устранения различий в стиле

Всегда будут существовать различия между разными программистами Go и между кодовыми базами разных команд. Однако в интересах Google и Alphabet, чтобы наша кодовая база была как можно более согласованной. (Подробнее о согласованности см. руководство). В связи с этим не стесняйтесь вносить улучшения стиля по мере необходимости, но вам не нужно придираться к каждому нарушению Руководства по стилю, которое вы обнаружите. В частности, эти документы могут меняться со временем, и это не повод вызывать лишнюю суету в существующих кодовых базах; достаточно писать новый код, используя новейшие лучшие практики, и со временем устранять проблемы поблизости.

Важно понимать, что вопросы стиля по своей природе субъективны и всегда сопряжены с компромиссами. Большая часть рекомендаций в этих документах субъективна, но, как и в случае с gofmt, в обеспечиваемом ими единообразии есть значительная ценность. Поэтому рекомендации по стилю не будут меняться без должного обсуждения, и программистам Go в Google рекомендуется следовать руководству по стилю, даже если они с чем-то не согласны.

Определения

Ниже приведены определения следующих слов, которые используются во всех документах по стилю:

Канонический: Устанавливает предписывающие и долговечные правила

В этих документах «канонический» используется для описания чего-либо, что считается стандартом, которому должен следовать весь код (старый и новый) и который не должен существенно меняться с течением времени. Принципы в канонических документах должны быть понятны как авторам, так и рецензентам, поэтому всё, что включается в канонический документ, должно соответствовать высоким стандартам. Как таковые, канонические документы обычно короче и предписывают меньше элементов стиля, чем неканонические документы.

https://google.github.io/styleguide/go#canonical
Нормативный: Призван установить согласованность

В этих документах «нормативный» используется для описания чего-либо, что является согласованным элементом стиля для использования рецензентами кода Go, чтобы предложения, терминология и обоснования были последовательными. Эти элементы могут меняться со временем, и эти документы будут отражать такие изменения, чтобы рецензенты могли оставаться последовательными и в курсе событий. От авторов кода на Go не ожидается знакомства с нормативными документами, но рецензенты будут часто использовать их в качестве справочного материала при проверке читаемости.

https://google.github.io/styleguide/go#normative
Идиоматичный: Распространённый и знакомый

В этих документах «идиоматичный» используется для обозначения чего-либо, что широко распространено в коде на Go и стало знакомым паттерном, который легко узнать. В целом, идиоматичный паттерн следует предпочитать неидиоматичному, если оба служат одной цели в контексте, поскольку именно это будет наиболее знакомо читателям.

https://google.github.io/styleguide/go#idiomatic

Дополнительные ссылки

Данное руководство предполагает, что читатель знаком с Effective Go, поскольку оно обеспечивает общую основу для кода на Go во всём сообществе Go.

Ниже приведены некоторые дополнительные ресурсы для тех, кто хочет самостоятельно изучить стиль Go, и для рецензентов, желающих предоставить в своих отзывах дополнительный контекст с ссылками. От участников процесса проверки читаемости Go не ожидается знакомства с этими ресурсами, но они могут упоминаться в качестве контекста при таких проверках.

Внешние ссылки

Спецификация языка Go
Часто задаваемые вопросы по Go
Модель памяти Go
Структуры данных в Go
Интерфейсы в Go
Поговорки Go
Выпуски Go Tip — следите за обновлениями.
Практики модульного тестирования — следите за обновлениями.

Соответствующие статьи Testing-on-the-Toilet

Дополнительные внешние материалы

Руководство по стилю Go

Руководство по стилю Go (Go Style Guide)

Оригинал: https://google.github.io/styleguide/go/guide

Примечание: Это часть серии документов, описывающих Стиль Go (Go Style) в Google. Данный документ является нормативным (normative) и каноническим (canonical). Подробнее см. в обзоре.

Принципы стиля

Существует несколько основополагающих принципов, которые суммируют подход к написанию читаемого кода на Go. Ниже перечислены атрибуты читаемого кода в порядке важности:

Понятность (Clarity): Цель и обоснование кода ясны читателю.
Простота (Simplicity): Код достигает своей цели наиболее простым способом.
Лаконичность (Concision): Код имеет высокое отношение сигнала к шуму.
Поддерживаемость (Maintainability): Код написан так, чтобы его было легко поддерживать.
Согласованность (Consistency): Код согласуется с более широкой кодобазой Google.

Решения

Решения по стилю Go

Оригинал: https://google.github.io/styleguide/go/decisions

Примечание: Это часть серии документов, описывающих Стиль Go в Google. Этот документ является нормативным, но не каноническим и подчиняется основному руководству по стилю. Подробнее см. в обзоре.

Об этом документе

В этом документе содержатся решения по стилю, призванные унифицировать и дать стандартные рекомендации, пояснения и примеры для советов, которые дают наставники по читаемости Go.

Этот документ не является исчерпывающим и будет пополняться со временем. В случаях, когда основное руководство по стилю противоречит приведенным здесь рекомендациям, руководство по стилю имеет приоритет, и этот документ должен быть обновлен соответственно.

Лучшие практики

Лучшие практики стиля Go (Go Style Best Practices)

Оригинал: https://google.github.io/styleguide/go/best-practices

Примечание: Это часть серии документов, описывающих Стиль Go (Go Style) в Google. Данный документ не является ни нормативным (normative), ни каноническим (canonical), а является вспомогательным документом к основному руководству по стилю. Подробнее см. в обзоре.

О документе (About)

В этом документе представлены рекомендации о том, как наилучшим образом применять Руководство по стилю Go. Эти рекомендации предназначены для типичных ситуаций, возникающих часто, но могут не применяться в каждом случае. По возможности обсуждаются несколько альтернативных подходов, а также соображения, которые учитываются при решении о том, когда их применять, а когда нет.

Google Go Style Guide — Руководство

О руководстве