Готовый перевод Style Guide for Python Code: Naming Conventions

Солгашения об обозначениях в библиотеке Python находятся в небольшом беспорядке, однако здесь есть рекомендуемые на данный момент стандарты обозначений.

Новые модули и пакеты (включая фреймворки от третьих лиц) следовало бы написать по этим стандартам, но когда существующая библиотека имеет отличный стиль написания, предпочтительнее чтобы было внутренне непротиворечиво.

Описание стилей именования

Существует много различных стилей обозначения

Они помогают в возможности разобраться, что же за стили обозначений используется, в зависимости от того, для чего они используются.

Следующие стили обозначений широко известны:

- b (одна буква в нижнем регистре)

- B (одна буква в верхнем регистре)

- lowercase (нижний регистр)

- lower_case_with_underscores (нижний регистр с подчёркиваниями)

- UPPERCASE (верхний регистр)

- UPPER_CASE_WITH_UNDERSCORES (верхний регистр с подчёркиваниями)

- CapitalizedWords, CapWords, CamelCase, StudlyCaps (так называемый «верблюжий» регистр).

Примечание. В «верблюжьем» регистре буквы сокращений записываются в верхнем регистре.
Например, HTTPServerError вместо HttpServerError.

- mixedCase (отличается от «верблюжьего» регистра строчной первой буквой)

- Capitalized_Words_With_Underscores (некрасиво!)

Есть также стиль, при котором применяется короткий уникальный префикс для группировки имён.

Этот стиль очень редко используется в Python и упомянут здесь только для полноты.

К примеру, функция os.stat() возвращает именованный кортеж, атрибуты которого по традиции называются st_mode, st_size, st_mtime и так далее.

(Это сделано, чтобы подчеркнуть соответствие атрибутов системному вызову функции stat() из POSIX)

Рекомендуемые соглашения по именованию

Нежелательные имена

Никогда не используйте одиночные символы l' (строчная эль), O' (прописная буква о) или I' (прописная буква и) в качестве имени переменной.

В некоторых шрифтах эти символы неотличимы от символов нуля и единицы. Вместо строчной l' используйте прописную L'.

Имена пакетов и модулей

Модули должны иметь короткие имена в нижнем регистре.

Знак подчёркивания применяется только в том случае, если это улучшает читаемость.

Пакеты должны иметь короткие имена в нижнем регистре, но использование подчеркиваний нежелательно.

Имена классов

Почти без исключений имена классов используют стиль CapWords.

Классы для использования сугубо внутри модуля имеют подчеркивание в начале имени.

Имена исключений

Так как исключения должны быть классами, они используют тот же стиль именования.

Имена глобальных переменных.

Имена функций

Имена функций должны быть в нижнем регистре с разделением слов знаком подчёркивания для улучшен читаемости.

Аргументы функций и методов

В качестве первого аргумента метода экземпляра всегда используется 'self'.

В качестве первого аргумента классового метода всегда используется 'cls'.

Если имя аргумента функции совпадает с зарезервированным ключевым словом, как правило, лучше добавить одно нижнее подчеркивание, чем использовать сокращение или орфографические коррупции. Таким образом, "print_" лучше, чем "prnt". (Возможно, лучше избегать таких совпадений, используя синонимы.)

Имена методов и переменные экземпляров

Используйте правила именования функций: слова состоящие из строчных букв, разделенные символом подчеркивания, в количестве необходимом для повышения читабельности.

Символ подчеркивания в начале (имени, прим. пер.) используйте только для непубличных методов и переменных экземпляра.

Python обрабатывает эти имена с именем класса: если класс Foo имеет атрибут с именем __a, он не будет доступен по (вызову, прим. пер.) Foo.__a. (Упорный пользователь может получить доступ вызовом Foo._Foo__a.)

Как правило, двойные подчеркивания в начале (имени, прим. пер.) должны использоваться только, чтобы избежать конфликтов имен с атрибутами внутри классов наследников.

Константы

Константы обычно определяются на уровне модуля и пишутся целиком прописными буквами с символом подчеркивания в качестве разделителя слов. Как пример: MAX_OVERFLOW и TOTAL.

Наследование

Всегда (необходимо, прим. пер.) решить, публичными или не публичными должны быть методы класса и переменные экземпляра (далее: "атрибуты"). В случае сомнений, выберите не публичный, ведь проще потом сделать его публичным, чем публичный атрибут не публичным.

Переведено на Нотабеноиде
http://notabenoid.org/book/1336/5357

Переводчики: rnd0011, Equilibrious, wuffur, armagetron

Gukoff, svartalf