8-900-374-94-44
Часть 1. Вступление
Часть 2. Заголовочные файлы
Часть 3. Область видимости
Часть 4. Классы
Часть 5. Функции
Часть 6. Специфика Google
Часть 7. Ещё возможности C++
Часть 8. Именование
Часть 9. Комментарии
Часть 10. Форматирование
Часть 11. Исключения из правил
Все мы при написании кода пользуемся правилами оформления кода. Иногда изобретаются свои правила, в других случаях используются готовые стайлгайды. Хотя все C++ программисты читают на английском легче, чем на родном, приятнее иметь руководство на последнем.
Эта статья является переводом части руководства Google по стилю в C++ на русский язык.
Исходная статья (fork на github), обновляемый перевод.
Это вступительная часть руководства, в которой рассматриваются общие вопросы «Зачем?»
Также после перевода будет несколько ответов на возможные вопросы.
Известно, что C++ очень мощный язык. Вместе с тем это сложный язык и, при неправильном использовании, может быть рассадником багов, затруднить чтение и поддержку кода.Цель руководства — управлять сложностью кода, описывая в деталях как стоит (или не стоит) писать код на C++.Правила этого руководства упростят управление кодом и увеличат продуктивность кодеров.
Style / Стиль — соглашения, которым следует C++ код.Стиль — это больше, чем форматирование файла с кодом.
Большинство open-source проектов, разрабатываемых Google, соответствуют этому руководству.
Примечание: это руководство не является учебником по C++: предполагается, что вы знакомы с языком.
Зачем нужен этот документ?
Есть несколько основных целей этого документа, внутренних Зачем, лежащих в основе отдельных правил. Используя эти цели можно избежать длинных дискуссий: почему правила такие и зачем им следовать.
Цели руководства следующие::
Использование единого стиля на кодовой базе позволяет переключиться на другие, более важные, вопросы.
Также, единый стиль способствует автоматизации. И, конечно, автоформат кода (или выравнивание #include-ов) работает правильно, если он соответствует требованиям утилиты. В остальных случаях из набора правил применяется только одно (наиболее подходящее), а некоторая гибкость в использовании правил позволяет людям меньше спорить.
Согласованность нашего кода с C++ кодом других организаций и сообществ весьма полезна.
Если возможности стандартного C++ или принятые идиомы языка облегчают написание программ, это повод использовать их. Однако, иногда стандарт и идиомы плохо подходят для задачи. В этих случаях (как описано ниже) имеет смысл ограничить или запретить использование некоторых стандартных возможностей. В некоторых случаях создаётся свой решение, но иногда используются внешние библиотеки (вместо стандартной библиотеки C++) и переписывание её под свой стандарт слишком затратно.
В C++ есть возможности, которые в целом не приветствуются по причине усложнения кода.
Однако, в часто используемом коде применение хитрых конструкций более оправданно благодаря многократному использованию, также новые порции кода станут более понятны.
В случае сомнений — проконсультируйтесь с лидером проекта.
Это очень важно для нашей кодовой базы, т.к. владельцы кода и команда поддержки меняются со временем: даже если сейчас все понимают код, через несколько лет всё может измениться.
С кодовой базой более 100 миллионов строк и тысячами инженеров, ошибки и упрощения могут дорого обойтись. Например, важно избегать замусоривания глобального пространства имён: коллизии имён очень сложно избежать в большой базе кода если всё объявляется в глобальном пространстве имён.
Оптимизация производительности иногда важнее, чем следование правилам в кодировании.
Намерение этого документа — обеспечить максимально понятное руководство при разумных ограничениях. Как всегда, здравый смысл никто не отменял. Этой спецификацией мы хотим установить соглашения для всего сообщества Google в C++, не только для отдельных команд или людей.
Относитесь со скепсисом к хитрым или необычным конструкциям: отсутствие ограничения не всегда есть разрешение. И, если не можешь решить сам, спроси начальника.
Сейчас код должен соответствовать C++17, т.е. возможности C++2x нежелательны. В дальнейшем, руководство будет корректироваться на более новые версии C++.
Не используйте нестандартные расширения.
Учитывайте совместимость с другим окружением, если собираетесь использовать C++14 and C++17 в свойм проекте.
Примечания:
ссылки могут вести на ещё не переведённые разделы руководства.
Несколько ответов/комментариев:
— Зачем перевод?
Лично мне удобнее с русским руководством. Обсуждать изменения в стайлгайде также лучше с русским текстом.
— Почему Google? Есть более (менее) популярные…?
Компания вполне известная, руководство не очень большое (можно перевести силами одного человека) и отвечает требуемым функциям — это руководство именно по стилю
— Но в руководстве Google декларируется использование устаревших (.
Любая форма приемлема, но их не следует смешивать. Выбирать
одно соглашение для документирования переменных уровня модуля и согласованности
с этим.
Делать:
* Для модуля TODO
* Вы также должны использовать расширение «sphinx.ext.todo«
.. _Руководство по стилю Google Python:
http://google.github.io/styleguide/pyguide.html
«»»
модуль_уровень_переменная1 = 12345
модуль_уровень_переменная2 = 98765
«»»int: Переменная уровня модуля задокументирована как встроенная.
Строка документации может занимать несколько строк. Тип может быть опционально указан
в первой строке, разделенные двоеточием.
«»»
def function_with_types_in_docstring (param1, param2):
«»»Пример функции с типами, задокументированными в строке документации.
Поддерживаются аннотации типа `PEP 484`_. Если атрибут, параметр и
возвращаемые типы аннотируются в соответствии с `PEP 484`_, их не нужно
включено в строку документации:
Аргументы:
param1 (int): первый параметр.
param2 (str): Второй параметр.
Возвращает:
bool: возвращаемое значение. True для успеха, False в противном случае.
.. _PEP 484:
https://www.python.org/dev/peps/pep-0484/
«»»
def function_with_pep484_type_annotations (param1: int, param2: str) -> bool:
«»»Пример функции с аннотациями типа PEP 484.
Аргументы:
param1: первый параметр.
param2: Второй параметр.
Возвращает:
Возвращаемое значение. True для успеха, False в противном случае.
«»»
def module_level_function (param1, param2 = None, * args, ** kwargs):
«»»Это пример функции уровня модуля.
Параметры функции должны быть задокументированы в разделе «Args«. Имя
каждого параметра является обязательным. Тип и описание каждого параметра
является необязательным, но его следует включить, если это не очевидно.
Если допустимы \*args или \*\*kwargs,
они должны быть перечислены как «*args« и «**kwargs«.
Формат параметра::
имя (тип): описание
Описание может занимать несколько строк.
которые имеют отношение к интерфейсу.
ValueError: Если `param2` равен `param1`.
«»»
если параметр1 == параметр2:
поднять ValueError(‘param1 не может быть равен param2’)
вернуть Истина
деф пример_генератор (n):
«»»Генераторы имеют раздел «Доходы« вместо раздела «Возвраты«.
Аргументы:
n (int): Верхний предел генерируемого диапазона от 0 до `n` — 1.
Урожайность:
int: Следующее число в диапазоне от 0 до `n` — 1.
Примеры:
Примеры должны быть написаны в формате doctest и должны иллюстрировать, как
для использования функции.
>>> print([i вместо i в example_generator(4)])
[0, 1, 2, 3]
«»»
для я в диапазоне (n):
выход я
класс ExampleError(Исключение):
«»»Исключения документируются так же, как и классы.
Метод __init__ может быть задокументирован либо на уровне класса,
docstring или как docstring самого метода __init__.
Любая форма приемлема, но их не следует смешивать.
Выбери один
соглашение для документирования метода __init__ и согласования с ним.
Примечание:
Не включайте параметр `self` в раздел «Args«.
Аргументы:
msg (str): Удобочитаемая строка, описывающая исключение.
code (:obj:`int`, необязательно): Код ошибки.
Атрибуты:
msg (str): Удобочитаемая строка, описывающая исключение.
code (int): Код ошибки исключения.
«»»
def __init__(я, сообщение, код):
self.msg = сообщение
селф.код = код
класс ExampleClass(объект):
«»»Сводная строка строки документации класса должна умещаться в одну строку.
Если у класса есть общедоступные атрибуты, они могут быть задокументированы здесь.
в разделе «Атрибуты« и придерживайтесь того же форматирования, что и
раздел «Args« функции. В качестве альтернативы атрибуты могут быть задокументированы
встроенный в объявление атрибута (см. метод __init__ ниже).
Свойства, созданные с помощью декоратора @property, должны быть задокументированы.
в методе получения свойства.
Атрибуты:
attr1 (str): Описание attr1.
attr2 (:obj:`int`, необязательно): описание attr2.
«»»
def __init__(я, параметр1, параметр2, параметр3):
«»»Пример строки документации по методу __init__.
Метод __init__ может быть задокументирован либо на уровне класса,
docstring или как docstring самого метода __init__.
Любая форма приемлема, но их не следует смешивать. Выбери один
соглашение для документирования метода __init__ и согласования с ним.
Примечание:
Не включайте параметр `self` в раздел «Args«.
Аргументы:
param1 (str): Описание `param1`.
param2 (:obj:`int`, необязательный): Описание `param2`. Несколько
линии поддерживаются.
param3 (:obj:`список` из :obj:`str`): Описание `param3`.
«»»
self.attr1 = параметр1
self.attr2 = параметр2
self.attr3 = param3 #: Комментарий документа *встроенный* с атрибутом
#: список атрибутов str: Doc comment *before* с указанным типом
self.
attr4 = [‘attr4’]
self.attr5 = Нет
«»»str: Строка документа *после* атрибута с указанным типом.»»»
@свойство
защита readonly_property (я):
«»»str: Свойства должны быть задокументированы в их методе получения.»»»
вернуть ‘readonly_property’
@свойство
защита readwrite_property (я):
«»»:obj:`list` of :obj:`str`: свойства с геттером и сеттером
должны быть задокументированы только в их методе получения.
Если метод установки содержит заметное поведение, он должен быть
упоминается здесь.
«»»
вернуть [‘readwrite_property’]
@readwrite_property.setter
def readwrite_property (я, значение):
ценить
def пример_метода (я, параметр1, параметр2):
«»»Методы класса аналогичны обычным функциям.
Примечание:
Не включайте параметр `self` в раздел «Args«.
Аргументы:
param1: первый параметр.
param2: Второй параметр.
Возвращает:
True в случае успеха, False в противном случае.
«»»
вернуть Истина
защита __special__(я):
«»»По умолчанию специальные элементы со строками документации не включаются.
Специальные члены — это любые методы или атрибуты, которые начинаются с и
заканчиваться двойным подчеркиванием. Любой специальный член со строкой документации
будет включено в вывод, если
Для параметра napoleon_include_special_with_doc установлено значение True.
Это поведение можно включить, изменив следующий параметр в
conf.py Сфинкса::
napoleon_include_special_with_doc = Истина
«»»
проходить
def __special_without_docstring__(я):
проходить
деф _частный (я):
«»»По умолчанию закрытые члены не включены.
Закрытые члены — это любые методы или атрибуты, начинающиеся с
подчеркивание и *не* особенные. По умолчанию они не включены
на выходе.
Это поведение можно изменить таким образом, чтобы частные члены *были* включены
изменив следующий параметр в conf.
py Sphinx::
napoleon_include_private_with_doc = Истина
«»»
проходить
def _private_without_docstring(я):
проходить Фото Эберхарда Гроссгаштайгера с сайта Unsplash
У каждого разработчика свой уникальный стиль и подход к написанию кода. Наш стили зависят от того, как мы научились программировать, от нашего предыдущего опыта и отчасти наших собственных личностей. Но, нам также необходимо последовательно работать как в командах, так и часто в больших и сложных организациях. Это десятки, или сотни, или тысячи уникальных стилей кодирования, работающих вместе и потенциально конфликтующих в единая кодовая база.
Если вся ваша команда работает с разными подходами, разными стилями и
разные предпочтения, это может начать создавать проблемы. Для работы
эффективно работать в команде, вы должны быть в состоянии объединить эти различные подходы
чтобы весь код, с которым вы имеете дело, был относительно прост для понимания,
легко расширяется, менее подвержен ошибкам и более удобен в сопровождении.
У большинства команд уже есть системы, помогающие стандартизировать их код. как правило, неформальные правила и стандарты, возникающие во время проверки кода внутри меньшие команды. Но по мере роста команд и сложности эти неформальные передовые практики недостаточно, и вам нужен более явный подход. В Google они явно изложили свой подход к созданию согласованного кода Python для своих проекты с открытым исходным кодом в их Руководство по стилю Python.
Давайте посмотрим, что такое Руководство по стилю Google, как оно структурировано их правила и рекомендации, и чему могут научиться различные инженерные команды. это. А затем мы быстро рассмотрим, как вы можете создайте свое собственное руководство по стилю и лучшие практики в коде с помощью Sourcery.
Прежде чем мы слишком углубимся в руководство по стилю, я хочу
разница между тем, что считается стилем, и тем, что считается форматированием. Есть
они частично пересекаются, но, как правило, форматирование
специально ориентированный на эстетические аспекты кода — начиная от строки
длину, интервалы, использование кавычек и скобок и т.
д. Руководство по стилю может
включать некоторые из этих элементов (например, в Руководстве по стилю Google большие фрагменты
раздел 3 сосредоточен на элементах форматирования), но в основном сосредоточен на
более структурные аспекты вашего кода, как мы обсудим ниже.
Для решения проблем с форматированием есть несколько отличных инструментов форматирования Python. включая:
Руководство по стилю Google состоит из более чем 40 наборов «что можно и чего нельзя» для
использовать в Python и разбит на два ключевых раздела — Правила языка Python и
Правила стиля Python. Вообще говоря, языковые правила используются для определения того, как
Google подходит к использованию (и, что важно, не использованию) и структурированию различных
элементы языка Python в своем коде. это критически
важный аспект Руководства по стилю для команд с разным уровнем
опыт работы на данном языке, потому что это помогает обеспечить ориентиры вокруг
структуру кода и какой тип расширенной языковой функции должна ваша команда
и не следует использовать.
Например — раздел 2.19 говорит, что вы не должны использовать какие-либо функции Python Power пока 2.10 говорит, что вы можете экономно использовать лямбда-функции (при условии, что они относительно короткий).
Раздел 2.19 — Правила Google Python Language Rules, объясняющие, почему не следует использовать Power Особенности
Раздел «Правила стиля» больше ориентирован на форматирование и стилистические приемы. что код должен следовать — в пределах от раздел 3.2 сосредоточены на длине строки, чтобы раздел 3.16 сосредоточены на практике именования.
Раздел 3.2 — Руководство по настройке Google Python Style Rules по длине строки
В обоих разделах руководства по стилю есть три основных причины или класса из рекомендаций:
Как и большинство руководств по стилю, Руководство по стилю Google создает два типа рекомендации по подходу при написании кода — правила структурирования кода и рекомендации по структурированию кода. Правило — это явный мандат вокруг того, как структурировать ваш код с минимальными исключениями, если таковые имеются, в то время как руководство является сильным предложением, которое может иметь исключения.
Сочетание правил и указаний в руководстве по стилю важно, потому что
существуют аспекты структуры кода, которые потенциально могут привести к огромным
головные боли, если есть вариации. Но для большинства рекомендаций полезно
дайте вашей команде возможность выйти за их пределы в определенных ситуациях .
Иначе, если все по строгому правилу, то может и не хватить
гибкость для вашей команды, чтобы работать, и это может привести к разочарованию.
Раздел 3.1 — рекомендации вокруг точки с запятой являются примерами явных правил
Раздел 3.18 — рекомендации по длине функции — это пример руководство, которое дает общие рекомендации по длине, но оставляет гибкость для отдельные функции.
В Руководстве по стилю Google есть только несколько рекомендаций, которые попали бы в категории «избегание опасности», и они охватывают несколько областей. Они прежде всего вокруг предотвращения появления ошибок, но раздел 3.8.2 также вводит некоторые интересные правила, касающиеся лицензирования и требований к интеллектуальной собственности, которые можно критические стандарты в проектах с открытым исходным кодом.
2.5 Глобальная переменная [рекомендация]
Хотя глобальные переменные не запрещены полностью, настоятельно не рекомендуется
используются из-за риска изменения поведения модуля во время их импорта.
Это яркий пример рекомендации в руководстве по стилю, используемой для
не одобрять стиль кодирования, который может значительно увеличить риск ошибок в
проект.
2.12 Значения аргументов по умолчанию [рекомендация]
Установка простых направляющих (но не сплошных запретов) по всему стилю руководство может помочь снизить риск критических ошибок. Можно использовать по умолчанию значения аргументов, если вы не используете изменяемые объекты в качестве значений по умолчанию.
2.18 Threading [Правило]
Это еще один раздел руководства по стилю, предназначенный для ограничения риска ошибок, но вместо того, чтобы создавать требование, потому что основным вариантом использования является риск, У Google есть правило не предполагать атомарность встроенных типов из-за риски вокруг пограничных случаев.
2.20 Современный Python: из будущего импорта [рекомендация]
Многие проекты Google с открытым исходным кодом должны быть совместимы с широким спектром
версий Python. Они рекомендуют использовать из **будущего** импортировать операторов в
помогите сделать переходы между версиями во время выполнения более плавными.
Эта рекомендация, вероятно,
что-то среднее между «Избегайте опасности» и «Применение лучших практик», поскольку оба они помогают
с уменьшением риска потенциальных ошибок и укрепляет передовой опыт
вокруг использования нового функционала.
3.8.2 Модули [Правило и руководство]
Критические требования в Руководстве по стилю относятся не только к тому, как код нужен быть структурированным, но также может относиться к бизнес-требованиям, требованиям ИС, и управление рисками безопасности/репутации. В рамках более широких комментариев и В разделе «Строки документации» Руководства по стилю Google излагает четкие требования к каждый модуль должен включать шаблон лицензии.
3.11 Файлы, сокеты и аналогичные ресурсы с отслеживанием состояния [Правило]
Помимо риска ошибок и бизнес-рисков, есть еще один важный параметр, который следует учитывать при
ваше руководство по стилю обеспечивает лучшие практики в отношении производительности кода. Здесь,
Google требует явного закрытия файлов и сокетов (и других подобных
закрываемые ресурсы) после завершения их использования, чтобы убедиться, что вы не
непреднамеренно съедают ресурсы.
3.17 Основное [Правило]
Как для тестирования, так и для автоматического документирования руководство по стилю Google требует
что вся функциональность исполняемого файла находится в пределах функция main() и что код всегда проверяет , если **name** == '**main**' перед выполнением
код. Это переносит важный аспект, поднятый в версии 2.5, который вы должны
не выполнять код непосредственно при импорте.
2.1 Lint [Guideline]
Если вы требуете или рекомендуете вашей команде использовать определенные инструменты или линтеры, полезно явно указать это в вашем руководстве по стилю. Здесь Google выкладывает рекомендации (и ограничения) по использованию Pylint.
2.2 Импорт [Правило]
Мы все часто полагаемся на импорт (как внутренний, так и внешний) и
непоследовательные подходы к обработке структур импорта могут привести к путанице и
сделать более вероятным, что мы внесем ошибки в наш код в будущем.
Google
излагает явные требования к тому, как импортировать модули и пакеты и в
в каких ограниченных ситуациях вы можете импортировать модуль в качестве псевдонима.
2.3 Пакеты [Правило]
Подобно приведенному выше правилу, руководство по стилю Google также содержит четкие правила для как импортировать пакеты четко. Для того, чтобы устранить путаницу, они требуют что вы импортируете каждый модуль по полному имени пакета.
2.4 Исключения [Руководство]
Определение того, как вы обрабатываете случаи, связанные с исключениями, ошибками и важные аспекты руководства по стилю, потому что несоответствие здесь может очень быстро привести к тому, что ваш код станет слишком сложным и трудным для понимания. Здесь Google изложил ряд явных условий, которые должны соблюдать исключения. следовать.
2.6 Вложенные/локальные/внутренние классы и функции [рекомендация]
Вложенные функции могут вызвать серьезные проблемы с читаемостью кода, но есть
также используйте случаи, когда они могут быть весьма полезными.
Эта рекомендация является
интересный пример того, как важно в руководстве по стилю
нейтральная позиция по вопросам, потому что это устраняет споры о том, действительно ли вы
должен или не должен всегда что-то делать. В данном случае — это на
усмотрение разработчика относительно того, когда использовать вложенные локальные функции или классы, с
несколько явных исключений, когда они обескуражены.
2.7 Понимание и выражения генератора [Рекомендация]
Эта рекомендация помогает создать очень четкие рекомендации по тому, когда или выражения генератора можно использовать — они должны быть простыми случаями и должны помещаться в одну строку, иначе их не следует использовать.
2.8 Итераторы и операторы по умолчанию [рекомендация]
Ранее я упоминал, что ключевой элемент руководства по стилю — встроенный
особенности языка, которые вы должны использовать и которых вам следует избегать. Когда это
приходит к итераторам и операторам по умолчанию для поддерживаемых типов, Руководство по стилю
настоятельно рекомендует использовать их из-за их простоты и
эффективность.
2.9 Генераторы [рекомендация]
Подобно приведенному выше правилу, Руководство по стилю Google рекомендует использовать генераторы, потому что они дают более простой код.
2.10 Лямбда-функции [рекомендация]
Как и в случае с вложенными функциями, в Руководстве по стилю Google говорится, что можно использовать лямбда-выражения, но только в определенных ситуациях и не обязательно поощряет их использование. Это предполагает, что все, что длиннее одной строки, является плохим вариантом использования для лямбда.
2.11 Условные выражения [рекомендация]
В Руководстве по стилю Google присутствует довольно постоянная тема. Вам следует используйте функциональность Python, которая помогает сделать ваш код короче и больше удобно для простых, однострочных вариантов использования, но, вероятно, не для более сложных ситуации. То же самое справедливо и для условных выражений.
2.13 Свойства [Руководство]
Как и приведенные выше несколько рекомендаций, рекомендации по свойствам сосредоточены на
на том, чтобы убедиться, что они не используются в тех случаях, когда они сделали бы вещи
слишком сложными (например, там, где они не соответствуют ожиданиям
типичный доступ к атрибуту и отсутствие реализации собственного дескриптора свойства).
Но, как и приведенные выше рекомендации, они не препятствуют общему использованию
свойства
2.14 Оценки True/False [рекомендация]
Во всех разделах правил языка Python есть разделы «за» и «против». вокруг того, почему вы можете или не хотите использовать данную функцию языка — и у этой рекомендации может быть мой любимый минус — «Может показаться странным для C/C++ Разработчики». В целом они рекомендуют использовать «неявное» значение false в Python. везде, где это возможно, но афера, которую они излагают, важна для размышления когда вы составляете собственное руководство по стилю. Убедитесь, что вы считаете, кто будут вносить свой вклад в вашу кодовую базу, каков их опыт и как это может повлиять на то, как вы должны структурировать свои лучшие практики.
2.16 Лексическая область видимости [руководство]
По сравнению с некоторыми предыдущими рекомендациями, которые содержали серьезные оговорки, эта
один из них относительно прост — можно использовать лексическую область видимости.
2.17 Декораторы функций и методов [рекомендация]
Вместо того, чтобы тратить большую часть раздела на то, следует ли использовать декораторы (здесь говорится, что их можно использовать с умом), большая часть этого раздела Руководство по стилю фокусируется на том, как обращаться с декораторами, когда вы их используете. особенно о том, как они вписываются в другие рекомендации в Руководстве по стилю.
2.19 Power Features [Правило]
В Google тысячи разработчиков пишут код на различных языки, и у них разный уровень знаний и опыта работы с Python. Здесь разработчикам прямо сказано не использовать «мощные функции» Python. потому что их может быть трудно понять разработчикам, которые а) не знакомы с ними или б) пересматривают код позже. Когда вы строите собственное руководство по стилю, важно учитывать, какой вариант опыта вы будет иметь в вашей команде и какие типы функций вы хотите, чтобы ваша команда использовала.
2.21 Типовой аннотированный код [рекомендация]
Интересно, что аннотирование типов — это тема, которая рассматривается в двух отдельных разделах.
разделы Руководства по стилю — здесь, в разделе «Правила языка Python» и
снова в разделе «Правила стиля Python». Эта часть руководства относительно
просто, просто заявив, что аннотация типа и проверка типа
сильно поощряется.
3.15 Getters & Setters [Руководство]
Это еще один раздел, который поощряет общее использование определенного типа функциональность в вашем коде — в данном случае функции получения и установки — но только где доступ сложный (не более широко).
Я не буду вдаваться в подробности некоторых аспектов согласованности и почему они полезно, как и для предыдущих разделов, потому что многие из дополнительных форматов целенаправленные рекомендации относительно просты.
3.1 Точки с запятой [Правило]
Не заканчивайте строки точкой с запятой и не используйте точки с запятой, чтобы иметь 2 оператора на та же линия.
3.2 Длина строки [Правило]
Максимальная длина строки, за некоторыми исключениями, должна составлять 80 символов.
3.3 Круглые скобки [Рекомендация]
В целом скобки следует использовать с осторожностью
3.4 Отступ [Правило]
Используйте 4 пробела для отступа.
3.5 Пустые строки [Правило]
Иметь 2 пустые строки между определениями верхнего уровня, 1 пустую строку между методами
определения и строка класса и первый метод, и 0 пустых строк после def линия.
3.6 Пробельное пространство [Правило]
Здесь руководство по стилю Google перечисляет ряд ограничений на то, когда следует не быть пробелом.
3.7 Строка Шебанга [Правило]
Включите только соответствующую строку Шебанга ( #!/usr/bin/env python3 (для поддержки
virtualenvs) или #!/usr/bin/python3 ) для файлов, которые будут выполняться
напрямую
3.8 Комментарии и строки документации [Руководство] (см. 3.8.2 Модули в разделе «Рекомендации по предотвращению опасности»)
Согласованное структурирование комментариев и строк документации важно для управления
общая согласованность и удобочитаемость проекта.
Вот руководство по стилю Google
подробно рассказывает о форматировании и структуре того, как подходить к строкам документации
для различных случаев комментарии.
3.10 Строки [Рекомендация]
Непоследовательность в форматировании строк может быстро привести к загромождению кода и боль, чтобы попытаться прочитать. В этом разделе Руководство по стилю Google излагает четкое руководство по последовательности структурирования строк (как длинных, так и коротких) strings и f strings) и содержит четкие рекомендации по структурированию и форматирование журналов и сообщений об ошибках.
3.12 Комментарии TODO [Правило]
Важным элементом управления сложной кодовой базой является размышление о том, как вы управлять известными проблемами или известными будущими улучшениями. Вот явное определение того, как вы должны использовать комментарии TODO — особенно, кто упоминается в TODO и что это значит.
3.13 Форматирование импорта [Рекомендация]
В разделе 2.2 есть ряд четких рекомендаций относительно того, как обращаться с
импорт и как его структурировать.
Вместо этого он ориентирован на форматирование импорта
и устанавливает определения, которые импортируются, должны быть определены в отдельных строках, что
импорт должен находиться в верхней части файлов и переходить от универсального к
специфический.
3.14 Утверждения [Руководство]
Подобно последним нескольким рекомендациям, этот раздел посвящен особенно при форматировании и структурировании вашего кода, чтобы у вас был только один оператор в заданной строке.
3.16 Именование [Рекомендация]
Имена сложны. А непоследовательное наименование может создать хаос в проекте. Это одна из причин, по которой мне очень нравится этот раздел Руководства по стилю Google. В нем указано, каких типов имен следует избегать (односимвольные имена, оскорбительные термины, определенные символы, которых следует избегать, и т. д.), дает соглашения об именах, чтобы гарантировать последовательность и дает рекомендации по именованию различных аспектов вашего кода.
3.18 Длина функции [рекомендация]
В руководстве по стилю можно создать множество рекомендаций по
требования к качеству кода (например, длина, сложность, рабочая память и т.
д.). Здесь,
Google предлагает ограничение на длину функции (40 символов), но также
признает, что есть исключения, когда вам может понадобиться нарушить это. Мне нравится
этот подход дает сильное предложение, но не делает его строгим правилом для
любой раздел руководства по стилю, основанный на качестве кода.
3.19 Типовые аннотации [Рекомендации]
Не путать с 2.21 Аннотированный код типа , в этом разделе ряд руководств по аннотированию кода и некоторые общие рекомендации когда и когда не аннотировать код
В команде Google работают десятки тысяч инженеров-программистов, так что вы можете
думать, что наличие подробного руководства по стилю явно полезно для компании
с таким уровнем сложности, но не имеет смысла для небольших организаций.
Но независимо от размера компании или команды, одна и та же истина будет
время, затрачиваемое на чтение, взаимодействие и поддержку раздела кода, уходит
быть на порядки больше, чем количество времени, которое вы собираетесь
тратить на его написание.