стиль написания кода python

Руководство по стилю кода PEP 8 в Python.

Синтаксис, правила написания кода в Python.

Одним из ключевых моментов PEP 8 является то, что код читается гораздо чаще, чем пишется. Приведенные здесь рекомендации предназначены для улучшения читабельности кода и обеспечения его согласованности с широким спектром кода Python. Как говориться в Дзене Python «Читаемость имеет значение».

Руководство по стилю о последовательности:

Однако, иногда рекомендации по стилю просто не применимы. В случае сомнений используйте свое решение. Посмотрите на другие примеры и решите, что выглядит лучше. И не стесняйтесь спрашивать! В общем, не нарушайте обратную совместимость только из за соблюдения PEP 8!

Некоторые другие веские причины игнорировать это руководство:

Разметка кода Python, PEP 8

Отступы в коде. TAB или пробелы? Максимальная длина строки с кодом. Разрыв строки до или после двоичного оператора? Пустые строки. Кодировка файла с кодом. Импорт. Кавычки в строках.

Пробелы в выражениях и операторах языка Python

Раздражители и другие рекомендации по пробелам в выражениях и операторах

Когда использовать запятые в коде на Python

Конечные запятые обычно необязательны, за исключением того, что они обязательны при создании кортежа из одного элемента

Комментарии в коде языка Python

Комментарии, которые противоречат коду, хуже, чем отсутствие комментариев. Всегда делайте приоритет обновления комментариев при изменении кода!

Соглашения об именах в Python

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

Рекомендации по программированию на Python

Код должен быть написан так, чтобы не зависеть от разных реализаций языка (PyPy, Jython, IronPython, Pyrex, Psyco и пр.).

Источник

Самоучитель

PEP 8

Python, подобно живому организму, развивается и приобретает новые возможности благодаря многочисленному международному сообществу согласно определенным правилам и стандартам PEP. PEP – Python Enhancement Proposal, предложения по развитию Python. Эти стандарты позволяют создавать унифицированную проектную документацию для новых утвержденных возможностей языка Python. Самый известный PEP имеет восьмой порядковый номер. PEP8 содержит перечень принципов написания красивого и лаконичного программного кода на языке Python.

Под названием каждого подраздела главы будет находиться по одному из 19 принципов философии Python (Zen of Python). Попытайтесь «прочувствовать» то, что имел в виду автор. Также, если хочется, вместо русской адаптации этих постулатов, увидеть оригинальный текст Тима Петерса, можно запустив вот такую программу.

Для чего придуман PEP8?

(Читаемость имеет значение)

PEP8 существует, чтобы улучшить “читабельность„ кода. Но почему этот параметр имеет настолько большую важность? Почему написание хорошо читаемого кода – один из фундаментальных принципов языка Python?

Как сказал создатель Python, Гвидо Ван Россум: «Код читается гораздо чаще, чем пишется». Вы можете провести несколько минут, или весь день, в процессе написания куска кода для, к примеру, аутентификации пользователя. Написав его, однажды, вы не будете писать его еще раз. Но вы точно вернетесь, чтобы прочитать его еще и еще раз. Эта часть кода может быть частью проекта, над которым вы работаете. Каждый раз, возвращаясь к этому файлу, придется вспомнить, что этот код делает и почему вы написали это именно так.

Если вы начинающий программист Python, вам может быть тяжело запомнить, что делает определенная часть кода по прошествии нескольких дней после ее написания. Однако, если вы будете следовать рекомендациям PEP8, можете быть уверены, ваш код будет в полном порядке. Вы будете знать, что добавили достаточно пробелов, в соответствии с разделением на логические блоки кода.

Соблюдение PEP8 особенно важно, если вы в поисках вакансии python-разработчика. Чистый и читаемый код показывает высокий профессионализм. Он говорит работодателю о вашем понимании правильного структурирования программного кода.

Если же вы более опытный Python-программист, тогда с помощи PEP8 можно с легкостью объединиться с другими программистами для работы над одной задачей. Хорошо читаемый код имеет в данном случае особую критичность. Люди, ранее не видевшие вас, но знакомые с вашим кодом, будут читать, понимая идею, которую вы хотели донести.

Негласная договоренность об именах

(Явное лучше, чем неявное)

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

Не использовать одиночные буквы l, O, или I в качестве каких‑либо имен из‑за риска спутать их с 1 и 0, в зависимости от шрифта.

Стили именования

В таблице ниже описаны некоторые из распространенных стилей именования в коде Python и указаны случаи, когда их следует использовать:

Помимо выбора правильных стилей именования в вашем коде, вы также должны тщательно выбирать сами имена. Ниже приведены несколько советов, как сделать это максимально эффективно.

Правильный выбор имени

Выбор имен для переменных, функций, классов и т. д. может оказаться неожиданно сложной задачей. При написании кода вы должны хорошо продумать свой выбор имен, так как это сделает ваш код более читаемым. Лучший способ назвать ваши объекты в Python — использовать описательные имена, чтобы было понятно, что представляет собой объект.

При именовании переменных у вас может возникнуть соблазн выбрать простые, состоящие из одной буквы имена в нижнем регистре, например x. Но если вы не используете x в качестве аргумента математической функции, непонятно, что представляет собой этот самый x. Представьте, что вы храните имя человека в виде строки и хотите использовать срез строки, чтобы по‑другому отформатировать его имя.

Вы можете получить что‑то вроде этого:

Это будет работать, но вам нужно будет отслеживать, что представляют собой x, y и z. Это также может сбивать с толку соавторов. Более правильный выбор имен будет примерно таким:

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

На первый взгляд, это может показаться очевидным выбором — это ведь отличное сокращением для double! Но представьте, что вернетесь к этому коду через несколько дней. Скорее всего, вы забудете, какой смысл вкладывали в эту функцию и вполне можете подумать, что это сокращение от database.

Следующий пример еще более понятен:

Та же самая философия относится и ко всем прочим типам данных и объектов в Python. Всегда пробуйте использовать наиболее емкие и лаконичные названия.

Расположение кода

(Красивое лучше, чем уродливое)

То, как Вы расположите ваш код, имеет огромную роль в повышении его читаемость. В этом разделе вы узнаете, как добавить вертикальные пробелы для улучшения восприятия вашего кода. Вы также узнаете, как правильно пользоваться ограничением в 79 символов на строку, рекомендованным в PEP8.

Монолитный код может быть труден для восприятия. Точно так же, слишком много пустых строк в коде делает его очень разреженным, что заставит читателя пролистывать его чаще, чем необходимо. Ниже приведены три основных правила использования вертикальных пробелов.

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

Обособьте определения методов внутри классов одной пустой строкой. Внутри класса все функции связаны друг с другом. Рекомендуется оставлять между ними только одну строку:

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

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

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

Максимальная длина строки и разрыв строки

PEP8 предлагает ограничить длину строки 79 символами. Это рекомендуется делать, чтобы вы имели возможность открывать несколько файлов рядом друг с другом, а также избегать переноса строк.

Конечно, не всегда возможно обеспечить длины всех операторов до 79 символов. PEP8 также описывает способы, позволяющие операторам занимать несколько строк. Python предполагает наличие продолжения строки, если код заключен в круглые, квадратные или фигурные скобки:

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

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

Отступы

(Должен быть один очевидный способ сделать это)

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

Отступ перед оператором вывода дает сигнал Python об условном выполнении только в случае, когда оператор if возвращает True. Ровно такой же отступ покажет Python, какой именно код выполнять при вызове функции или какой код имеет отношение к данному классу. Ключевых правил расстановки отступов всего два и они ниже:

Используйте четыре последовательных пробела для отступа;

Отдавайте предпочтение пробелам, а не табуляции.

Пробелы против Табуляции

Вы можете настроить ваш редактор кода на вставку четырех пробелов, когда вы нажимаете клавишу Tab. Также необходимо иметь в виду, что в Python 3 запрещено смешение пробелов и табуляции. Изначально выберите, как именно вы будете выставлять отступы и придерживайтесь этого выбора. Иначе, вместо выполнения кода, вы получите ошибку.

Комментарии

(Если реализацию трудно объяснить, это была плохая идея)

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

Используйте длину комментариев при документации не более 72 символов;

Не используйте сокращения, начинайте предложения с заглавной буквы;

Не забывайте актуализировать комментарии, при изменении кода.

Пример простейшего комментария:

Пробелы в выражениях и утверждениях

(Разреженное лучше, чем плотное)

Полезность пробелов в выражениях и операторах трудно переоценить. Если пробелов недостаточно, код может быть трудночитаемым, так как все сгруппированы вместе. Если пробелов слишком много, может быть сложно визуально объединить строки кода в, логически связанные, блоки.

Окружите следующие бинарные операторы одним пробелом с каждой стороны:

Источник

Разметка кода Python, PEP 8

Разметка кода

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

Отступы:

Используйте 4 пробела для добавления отступа.

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

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

Правильно:

Не правильно:

Правило 4 пробелов не является обязательным для строк продолжения.

По желанию:

Закрывающая скобка в многострочных конструкциях может располагаться либо под первым символом последней строки списка:

или может быть на уровне первого символа строки, которая начинает многострочную конструкцию:

TAB или пробелы?

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

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

Python 3 запрещает смешивать использование табуляции и пробелов для отступа. Код с отступом в виде комбинации символов табуляции и пробелов должен быть преобразован исключительно в пробелы.

Максимальная длина строки с кодом:

Ограничьте все строки максимум 79 символами.

Для строк документации или комментариев длина строки должна быть ограничена 72 символами.

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

Перенос по умолчанию в большинстве редакторов нарушает визуальную структуру кода, что делает его более трудным для понимания. Данные ограничения приняты для того, чтобы избежать автоматического переноса строк в редакторах с шириной окна, установленной на 80 символов, даже если он помещает маркер курсора в последний столбец. Некоторые IDE могут вообще не иметь авто-переноса строк.

Некоторые команды разработчиков предпочитают более длинные строки при написании кода. Исключительно для поддержания такого кода внутри команды, разрешается увеличить ограничение длины строки до 99 символов, при условии, что комментарии и документация должна быть ограничена 72 символами

Стандартная библиотека Python консервативна и требует ограничения строки до 79 символов (и строки документации/комментариев до 72).

Еще один такой случай возможен с assert утверждениями.

Удостоверьтесь, что сделали отступ в 4 пробела для продолжения строки кода.

Перенос строки до или после двоичного оператора?

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

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

В коде Python допускается перенос до или после двоичного оператора, если есть такое соглашение. Для нового кода предлагается математический стиль.

Пустые строки:

Определения функций и классов верхнего уровня должны быть заключены в две пустые строки.

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

Дополнительные пустые строки могут использоваться для разделения групп связанных функций. Пустые строки могут быть пропущены между связкой связанных строк (например, набором фиктивных реализаций).

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

Кодировка файла с кодом:

Код в основном дистрибутиве Python всегда должен использовать UTF-8 (или ASCII в Python 2).

Файлы, использующие ASCII (в Python 2) или UTF-8 (в Python 3), не должны иметь декларации кодировки.

Для Python 3.0 и выше, для стандартной библиотеки предписана следующая политика. Все идентификаторы в стандартной библиотеке Python ДОЛЖНЫ использовать идентификаторы только ASCII и ДОЛЖНЫ использовать английские слова везде, где это возможно (сокращения и технические термины, которые не являются английскими). Кроме того, все строковые литералы и комментарии также должны быть в ASCII.

Единственными исключениями являются:

Проектам с открытым исходным кодом с глобальной аудиторией рекомендуется придерживаться аналогичной политики.

Импорт:

Импорт обычно должен быть в отдельных строках:

Это нормально, хотя:

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

Импорт должен быть сгруппирован в следующем порядке:

Вы должны поставить пустую строку между каждой группой импорта.

Рекомендуется абсолютный импорт, так как он обычно более читабелен и, как правило, ведет себя лучше (или, по крайней мере, дает лучшие сообщения об ошибках), если система импорта настроена неправильно (например, когда каталог внутри пакета заканчивается в sys.path ):

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

Код стандартной библиотеки должен избегать сложных макетов пакетов и всегда использовать абсолютный импорт.

Неявный относительный импорт никогда не должен использоваться и был удален в Python 3.

При импорте класса из модуля, обычно можно записать следующее:

Если это написание вызывает локальные конфликты имен, то запишите импорт через точку:

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

При повторной публикации имен, все же применяются приведенные ниже рекомендации, касающиеся открытых и внутренних интерфейсов.

Расположение имен «dunders» в коде:

Кавычки в строках:

В Python одинарные и двойные кавычки функционально одинаковы. PEP не дает рекомендации какие из них предпочтительнее. Выберите правило и придерживайтесь его. Если, например, строка содержит одинарные кавычки, чтобы избежать обратной косой черты в строке, используйте дополнительно двойные кавычки. Это улучшает читаемость.

Для строк с тройными кавычками всегда используйте символы двойной кавычки, чтобы соответствовать соглашению с документированной строкой в PEP 257.

Источник

Как оформлять код

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

PEP 8 (Python Enhancement Proposals, англ. или предложения по улучшению Python, рус.) создан на основе рекомендаций Гуидо ван Россума с добавлениями от Барри. Если где-то возникал конфликт, мы выбирали стиль Гуидо. И, конечно, этот PEP может быть неполным (фактически, он, наверное, никогда не будет закончен).

Ключевая идея Гуидо такова: код читается намного больше раз, чем пишется. Собственно, рекомендации о стиле написания кода направлены на то, чтобы улучшить читаемость кода и сделать его согласованным между большим числом проектов. В идеале, весь код будет написан в едином стиле, и любой сможет легко его прочесть.

Это руководство о согласованности и единстве. Согласованность с этим руководством очень важна. Согласованность внутри одного проекта еще важнее. А согласованность внутри модуля или функции — самое важное. Но важно помнить, что иногда это руководство неприменимо, и понимать, когда можно отойти от рекомендаций. Когда вы сомневаетесь, просто посмотрите на другие примеры и решите, какой выглядит лучше.

Две причины для того, чтобы нарушить данные правила:

Содержание

Внешний вид кода

Отступы

Используйте 4 пробела на каждый уровень отступа.

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

Закрывающие круглые/квадратные/фигурные скобки в многострочных конструкциях могут находиться под первым непробельным символом последней строки списка, например:

либо быть под первым символом строки, начинающей многострочную конструкцию:

Табуляция или пробелы?

Пробелы — самый предпочтительный метод отступов.

Табуляция должна использоваться только для поддержки кода, написанного с отступами с помощью табуляции.

Python 3 запрещает смешивание табуляции и пробелов в отступах.

Python 2 пытается преобразовать табуляцию в пробелы.

Максимальная длина строки

Ограничьте длину строки максимум 79 символами.

Для более длинных блоков текста с меньшими структурными ограничениями (строки документации или комментарии), длину строки следует ограничить 72 символами.

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

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

Стандартная библиотека Python консервативна и требует ограничения длины строки в 79 символов (а строк документации/комментариев в 72).

Предпочтительный способ переноса длинных строк является использование подразумеваемых продолжений строк Python внутри круглых, квадратных и фигурных скобок. Длинные строки могут быть разбиты на несколько строк, обернутые в скобки. Это предпочтительнее использования обратной косой черты для продолжения строки.

Обратная косая черта все еще может быть использована время от времени. Например, длинная конструкция with не может использовать неявные продолжения, так что обратная косая черта является приемлемой:

Ещё один случай — assert.

Сделайте правильные отступы для перенесённой строки. Предпочтительнее вставить перенос строки после логического оператора, но не перед ним. Например:

Пустые строки

Отделяйте функции верхнего уровня и определения классов двумя пустыми строками.

Определения методов внутри класса разделяются одной пустой строкой.

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

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

Python расценивает символ control+L как незначащий (whitespace), и вы можете использовать его, потому что многие редакторы обрабатывают его как разрыв страницы — таким образом логические части в файле будут на разных страницах. Однако, не все редакторы распознают control+L и могут на его месте отображать другой символ.

Кодировка исходного файла

Кодировка Python должна быть UTF-8 (ASCII в Python 2).

Файлы в ASCII (Python 2) или UTF-8 (Python 3) не должны иметь объявления кодировки.

В стандартной библиотеке, нестандартные кодировки должны использоваться только для целей тестирования, либо когда комментарий или строка документации требует упомянуть имя автора, содержащего не ASCII символы; в остальных случаях использование \x, \u, \U или \N — наиболее предпочтительный способ включить не ASCII символы в строковых литералах.

Начиная с версии python 3.0 в стандартной библиотеке действует следующее соглашение: все идентификаторы обязаны содержать только ASCII символы, и означать английские слова везде, где это возможно (во многих случаях используются сокращения или неанглийские технические термины). Кроме того, строки и комментарии тоже должны содержать лишь ASCII символы. Исключения составляют: (а) test case, тестирующий не-ASCII особенности программы, и (б) имена авторов. Авторы, чьи имена основаны не на латинском алфавите, должны транслитерировать свои имена в латиницу.

Проектам с открытым кодом для широкой аудитории также рекомендуется использовать это соглашение.

Импорты

В то же время, можно писать так:

Импорты должны быть сгруппированы в следующем порядке:

Вставляйте пустую строку между каждой группой импортов.

Тем не менее, явный относительный импорт является приемлемой альтернативой абсолютному импорту, особенно при работе со сложными пакетами, где использование абсолютного импорта было бы излишне подробным:

В стандартной библиотеке следует избегать сложной структуры пакетов и всегда использовать абсолютные импорты.

Если такое написание вызывает конфликт имен, тогда пишите:

Пробелы в выражениях и инструкциях

Избегайте использования пробелов в следующих ситуациях:

Другие рекомендации

Комментарии

Комментарии, противоречащие коду, хуже, чем отсутствие комментариев. Всегда исправляйте комментарии, если меняете код!

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

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

Ставьте два пробела после точки в конце предложения.

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

Блоки комментариев

Блок комментариев обычно объясняет код (весь, или только некоторую часть), идущий после блока, и должен иметь тот же отступ, что и сам код. Каждая строчка такого блока должна начинаться с символа # и одного пробела после него (если только сам текст комментария не имеет отступа).

Абзацы внутри блока комментариев разделяются строкой, состоящей из одного символа #.

«Встрочные» комментарии

Старайтесь реже использовать подобные комментарии.

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

Комментарии в строке с кодом не нужны и только отвлекают от чтения, если они объясняют очевидное. Не пишите вот так:

Впрочем, такие комментарии иногда полезны:

Строки документации

Контроль версий

Если вам нужно использовать Subversion, CVS или RCS в ваших исходных кодах, делайте вот так:

Вставляйте эти строки после документации модуля перед любым другим кодом и отделяйте их пустыми строками по одной до и после.

Соглашения по именованию

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

Главный принцип

Имена, которые видны пользователю как часть общественного API должны следовать конвенциям, которые отражают использование, а не реализацию.

Описание: Стили имен

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

Обычно различают следующие стили:

Ещё существует стиль, в котором имена, принадлежащие одной логической группе, имеют один короткий префикс. Этот стиль редко используется в python, но мы упоминаем его для полноты. Например, функция os.stat() возвращает кортеж, имена в котором традиционно имеют вид st_mode, st_size, st_mtime и так далее. (Так сделано, чтобы подчеркнуть соответствие этих полей структуре системных вызовов POSIX, что помогает знакомым с ней программистам).

В библиотеке X11 используется префикс Х для всех public-функций. В python этот стиль считается излишним, потому что перед полями и именами методов стоит имя объекта, а перед именами функций стоит имя модуля.

В дополнение к этому, используются следующие специальные формы записи имен с добавлением символа подчеркивания в начало или конец имени:

Предписания: соглашения по именованию

Имена, которых следует избегать

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

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

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

Модули должны иметь короткие имена, состоящие из маленьких букв. Можно использовать символы подчеркивания, если это улучшает читабельность. То же самое относится и к именам пакетов, однако в именах пакетов не рекомендуется использовать символ подчёркивания.

Так как имена модулей отображаются в имена файлов, а некоторые файловые системы являются нечувствительными к регистру символов и обрезают длинные имена, очень важно использовать достаточно короткие имена модулей — это не проблема в Unix, но, возможно, код окажется непереносимым в старые версии Windows, Mac, или DOS.

Когда модуль расширения, написанный на С или C++, имеет сопутствующий python-модуль (содержащий интерфейс высокого уровня), С/С++ модуль начинается с символа подчеркивания, например, _socket.

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

Имена классов должны обычно следовать соглашению CapWords.

Вместо этого могут использоваться соглашения для именования функций, если интерфейс документирован и используется в основном как функции.

Обратите внимание, что существуют отдельные соглашения о встроенных именах: большинство встроенных имен — одно слово (либо два слитно написанных слова), а соглашение CapWords используется только для именования исключений и встроенных констант.

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

Так как исключения являются классами, к исключениями применяется стиль именования классов. Однако вы можете добавить Error в конце имени (если, конечно, исключение действительно является ошибкой).

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

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

Добавляйте в модули, которые написаны так, чтобы их использовали с помощью from M import *, механизм __all__, чтобы предотвратить экспортирование глобальных переменных. Или же, используйте старое соглашение, добавляя перед именами таких глобальных переменных один символ подчеркивания (которым вы можете обозначить те глобальные переменные, которые используются только внутри модуля).

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

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

Стиль mixedCase допускается в тех местах, где уже преобладает такой стиль, для сохранения обратной совместимости.

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

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

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

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

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

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

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

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

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

Примечание: есть некоторые разногласия по поводу использования __ имена (см. ниже).

Константы

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

Проектирование наследования

Обязательно решите, каким должен быть метод класса или экземпляра класса (далее — атрибут) — публичный или непубличный. Если вы сомневаетесь, выберите непубличный атрибут. Потом будет проще сделать его публичным, чем наоборот.

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

Мы не используем термин «приватный атрибут», потому что на самом деле в python таких не бывает.

Другой тип атрибутов классов принадлежит так называемому API подклассов (в других языках они часто называются protected). Некоторые классы проектируются так, чтобы от них наследовали другие классы, которые расширяют или модифицируют поведение базового класса. Когда вы проектируете такой класс, решите и явно укажите, какие атрибуты являются публичными, какие принадлежат API подклассов, а какие используются только базовым классом.

Теперь сформулируем рекомендации:

Примечание 1: Свойства (properties) работают только в классах нового стиля (в Python 3 все классы являются таковыми).

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

Примечание 1: Будьте внимательны: если подкласс будет иметь то же имя класса и имя атрибута, то вновь возникнет конфликт имен.

Примечание 2: Механизм изменения имен может затруднить отладку или работу с __getattr__(), однако он хорошо документирован и легко реализуется вручную.

Примечание 3: Не всем нравится этот механизм, поэтому старайтесь достичь компромисса между необходимостью избежать конфликта имен и возможностью доступа к этим атрибутам.

Общие рекомендации

Для минимизации усилий можно воспользоваться декоратором functools.total_ordering() для реализации недостающих методов.

Старая форма записи запрещена в python 3.

К примеру, пишите вот так:

Простое написание «except:» также перехватит и SystemExit, и KeyboardInterrupt, что породит проблемы, например, сложнее будет завершить программу нажатием control+C. Если вы действительно собираетесь перехватить все исключения, пишите «except Exception:».

Хорошим правилом является ограничение использования «except:», кроме двух случаев:

startswith() и endswith() выглядят чище и порождают меньше ошибок. Например:

Когда вы проверяете, является ли объект строкой, обратите внимание на то, что строка может быть unicode-строкой. В python 2 у str и unicode есть общий базовый класс, поэтому вы можете написать:

Специальные требования для оформления текстов для моих курсантов

В самом начале скрипта с кодом Python необходимо указывать следующие атрибуты:

Источник