какова максимальная длина строки кода по pep 8 с комментариями
PEP 8: каким должен быть код на Python
Python имеет определенные стандарты кода, которым стараются следовать все программисты. Эти стандарты описаны в документации PEP8.
Любой популярный язык программирования требует, чтобы разные программисты писали примерно одинаковый по стилю код. Отклонение от нормы не вызовет ошибки при выполнении программы, но считается плохим тоном среди профессиональных программистов.
Почему важно стандартизировать код?
На самом деле программисты проводят большую часть за анализом кода, а не за его написанием. Это происходит потому, что ничего не пишется с нуля. Берутся уже готовые и отлаженные решения, которые модифицируются под определенный проект. Кроме того, часто необходимо поддерживать уже существующие программы, код которых насчитывает сотни тысяч строк.
Если каждый программист будет писать код с разным стилем, то его анализ станет очень трудной задачей. Поэтому важно, чтобы Python-разработчики следовали определенным соглашениям, которые позволяют стандартизировать код, сделать его более понятным любому специалисту.
Рекомендации по созданию красивого кода на Python не определяют стиль кода полностью. Поэтому программист может делать некоторые вещи на своё усмотрение, однако он всё ещё должен следовать тем указаниям, которые определены в стандарте.
Внутри команды разработчиков может выработаться особый стиль написания кода, который может в некоторых местах нарушать принятые соглашения. Это нередкая и допустимая ситуация, однако программист должен помнить, что если он уйдет из этой команды, ему придется заново переучиваться писать код в соответствии с принятыми стандартами.
Разметка кода на Python
Этот раздел содержит указания, определяющие, как оформлять код на Python 3 (пробелы, отступы, строки).
Отступы
Для обозначения нового уровня вложенности используется четыре пробела.
При разделении аргументов функции на несколько строк размер отступа может быть разным.
Если это объявление или вызов функций (нет тела функции), то можно либо выравнивать следующие строки по открывающейся скобке:
либо использовать четыре пробела, но с обязательным переносом первой строки:
Если после списка аргументов следует еще какой-либо код (например, если это объявляется функция), то к отступу аргументов добавляется еще 4 пробела:
Это делается для того, чтобы отделить аргументы от тела функции.
В случае с оператором if, программист может как использовать, так и не использовать экстра отступы:
Если не использовать дополнительные пробелы, то, при желании, можно отделить тело условного оператора однострочным комментарием. Это может улучшить читаемость в некоторых редакторах кода из-за подсветки комментария.
Закрывающая конструкция в функции или структуре может располагаться под первым символом нижней строки:
Также её можно поместить в самое начало строки:
Программист также может использовать табуляцию, однако пробелы более предпочтительны. Кроме того, использование и табуляции, и пробелов не просто не приветствуется, но и вызывает ошибки интерпретатора.
Максимальная длина строки
Благодаря этим ограничениям программисты могут открывать сразу несколько файлов с кодом на одном экране, комфортно работать на маленьких экранах (ультрабуки, нетбуки) и легко понимать код.
Круглые скобки — лучший способ реализовать разделение кода на несколько строк. Однако программисты также могут использовать знак обратной косой черты « \ «.
Бинарные операторы и пробелы
Кроме того, если операторы используются в многострочном выражении, то они всегда должны переноситься вместе с правым операндом:
Пустые строки
Определения внешних классов и функций окружается двумя пустыми строками (две строки сверху).
Методы внутри класса отделяются одной пустой строкой.
Группы функций можно разделить дополнительной пустой строкой. Группы связанных строк кода можно отделять пустыми строками для того, чтобы было проще разобраться в логике программы.
Нельзя использовать пустые строки между внешним и вложенным блоком кода.
Кодировка
Если нужно использовать символы других кодировок, следует пользоваться экранирующими последовательностями: \x, \u, \U, \N.
Импорт
Импорт каждого нового модуля должен происходить в новой строке:
При импорте нескольких частей модуля можно писать их в одной строке через запятую:
Подключение модулей всегда находятся в начале файла, ниже строк документации и выше объявления констант.
Импорты должны быть разделены по группам, между которыми ставится пустая строка:
Использовать «*» при импорте считается плохим тоном. Дело в том, что такой импорт не дает представления об именах, которые находятся в импортированном пространстве имен, что не только сбивает с толку, но и может привести к ошибкам.
Кавычки в строках
В Python можно использовать как одинарные, так и двойные кавычки. Однако, если в строке используются двойные кавычки, то программист должен выделять строку одинарными и наоборот. Это позволяет повысить читаемость строки.
Для строк документации обязательно используется три двойных кавычки. Более подробнее это описано в стандарте PEP 257.
Пробелы в выражениях и операторах
При правильном применении пробелы повышают читаемость кода, однако, в определенных ситуациях следует избегать их использования.
Использование запятых
Конечные запятые, обычно, необязательны. Исключением является использование запятых в кортеже, состоящим из одного элемента. В этом случае следует поместить содержимое кортежа в круглые скобки.
Использование запятых особенно актуально при работе с системой контроля версий, когда список значений или аргументов должен постоянно расширяться. В этом случае каждый новый аргумент пишется с новой строки.
Комментарии
Комментарии — это важная часть любого проекта, потому что с их помощью можно понять, как работает код и какие особенности он имеет. Программисты использую комментарии не только для того, чтобы другие специалисты могли понять код, но и чтобы самим не забыть, как и зачем они реализовали те или иные функции.
Комментарии должны отражать суть кода, а не противоречить ему. Если код по какой-то причине изменяется, комментарии также необходимо изменить.
Все комментарии должны быть законченными предложениями, и если первое слово не является идентификатором, то оно должно начинаться с заглавной буквы.
Комментарии можно писать не на английском, если вы уверены на 120%, что этот код никогда не будут смотреть люди не говорящие на вашем языке.
Блочные комментарии
Блочные комментарии используются, когда необходимо объяснить действий какого-либо блока кода. Как правило, такие комментарии размещаются над блоком кода на отдельной строке.
Комментарии «в строке»
Это комментарии, которые объясняют действия строки кода и пишутся в той же строке, что и код. Они должны отделяться от кода не менее чем двумя пробелами.
Такие комментарии не рекомендуется использовать, потому что в большинстве случаев они объясняют очевидные вещи и не несут никакой практической пользы.
Однако в некоторых случаях они могут быть полезны, когда настоящее назначение строки не очевидно:
Строки документации
Все открытые модули, функции, классы и их составляющие должны документироваться. Это правило не относится к приватным методам, однако между строкой с «def» и телом метода можно написать комментарий, который описывает назначение метода.
Более подробно про соглашение о документации рассказано в PEP 257. Кавычки, показывающие окончания строк документации, должны переносится на новую строку.
Однако, если документация состоит из одной строки, то кавычки не переносятся.
Правила по выбору имён
Соглашения по выбору имён в Python неточны, поэтому не существует списка, полностью определяющего стиль наименований в Python. Для всех новых пакетов и модулей должен использоваться текущий стандарт наименований.
Главный принцип
Если имя является открытой частью интерфейса прикладного программирования, то оно должно отражать не реализацию, а использование.
Стили имен
Выбирать имена в Python можно в соответствии с одним из многих стилей. Определить, какой стиль наименования используется, можно независимо от того, для чего он используется.
Обычно используются следующие стили:
Имена, которые лучше не использовать
Никогда не используйте строчные английские буквы: l («эл»), O (заглавная «о») и I (заглавная «ай»). Заглавная «о» неотличима от нуля, а «l» и «I» друг от друга.
Если всё же возникла необходимость использовать l («эл»), замените её на заглавную «L».
Имена пакетов и моделей
Модули должны иметь короткие имена в нижнем регистре. В именах модулей допускается использовать нижние подчеркивания, если это улучшает читаемость.
Если модуль на C или C++ сопровождается модулем Python, обеспечивающим более высокоуровневый интерфейс, то имя C/C++ модуля начинается с символа нижнего подчеркивания (_modulename).
Имена классов
Классам дают имена в соответствии со стилем наименования CapitalizedWords.
Имена исключений
Из-за того что исключения по сути являются классами, к ним применяется то же соглашение об наименованиях, что и для классов.
Программист может добавить суффикс «Error», чтобы подчеркнуть, что исключение является ошибкой.
Имена глобальных переменных
Глобальные переменные именуются по тем же соглашениям, что и функции. Кроме того, глобальные переменные стоит использовать только в пределах одного модуля.
__all__ — это список доступных для импорта объектов, то есть публичных.
Имена функций и переменных
Для имен функций используется нижний регистр. Если необходимо повысить читаемость, можно разделять слова символом нижнего подчеркивания.
Имена переменных выбираются по тем же правилам, что и имена функций.
В случаях, если требуется сохранить обратную совместимость с библиотекой (например, threading.py), допускается использовать mixedCase.
Имена аргументов функций и методов
Для методов экземпляра в качестве первого аргумента всегда используется self, а для методов класса — cls.
Если аргумент функции имеет имя, которое конфликтует с зарезервированным ключевым словом языка, следует добавить в его конец символ нижнего подчеркивания. Это лучше, чем сокращать или менять имя с потерей смысла.
Имена переменных и методов экземпляров класса
Тот же стиль, что и для функций: нижний регистр и нижние подчеркивания при необходимости.
Константы
Константы определяются на уровне подключения модулей и пишутся в верхнем регистре с разделением слова символами подчеркивания.
Правила оформления кода по PEP8 на Python. Руководство для программиста
Введение в PEP8 (Python Enhancement Proposal #8)
Документ Python Enhancement Proposal #8 (сокращенно РЕР8) содержит предложения по стилевому оформлению кода программ на языке Python. Вообще говоря, вы вправе форматировать свой код так, как считаете нужным. Однако применение единообразного стиля облегчит изучение кода другими людьми и улучшит его удобочитаемость. Совместное использование общего стиля с другими Руthоn-программистами в рамках большого сообщества способствует улучшению качества программ при коллективной работе над проектами. Но даже если единственный человек, который когда-либо будет читать ваш код, — это вы, соблюдение рекомендаций РЕР 8 облегчит внесение последующих изменений в код.
Документ РЕР8 содержит детализированные правила написания кода на Python. По мере развития языка этот документ постоянно обновляется. Было бы неплохо, если бы вы прочитали целиком все руководство
Ниже приведены некоторые правила, которых следует обязательно придерживаться.
Пробелы
В языке Python пробелы имеют синтаксическое значение. Особое значение Pythоn-программисты придают влиянию пробелов на удобочитаемость кода.
Имена
В документе РЕР8 для различных элементов языка предлагается свой стиль имен. Благодаря этому можно легко определить в процессе чтения кода, какому типу соответствует то или иное имя:
Выражения и инструкции
Одно из положений дзен-философии Python гласит: «Должен существовать один — и предпочтительно только один — очевидный способ сделать это». В рекомендациях документа РЕР8 предпринимается попытка кодифицировать такой стиль написания выражений и предложений.
В каждом подразделе модули должны располагаться в алфавитном порядке.
Что следует запомнить
Best Practices Python PEP8 Code Style — Стиль кода для написания функций
Если вы спросите программистов Python, что им больше всего нравится в Python, они часто будут ссылаться на его высокую читабельность. Действительно, высокий уровень читабельности лежит в основе дизайна языка Python, следуя общепризнанному факту, что код читается гораздо чаще, чем пишется.
Одной из причин высокой читабельности кода Python является его полный набор рекомендаций PEP8 по стилю кода и «Pythonic» идиом.
Когда ветеран Python-разработчик (Pythonista) называет части кода не «Pythonic», они обычно означают, что эти строки кода не следуют общим правилам и не выражают свое намерение в том, что считается лучшим (слушайте: наиболее читаемый) путь.
В некоторых случаях не было достигнуто соглашения о том, как выразить намерение в коде Python, но такие случаи редки.
Явный код
Хотя в Python возможен любой вид черной магии, наиболее явный и простой способ предпочтителен.
Плохо
Хорошо
В приведенном выше хорошем коде x и y явно принимаются от вызывающей стороны, и возвращается явный словарь. Разработчик, использующий эту функцию, точно знает, что делать, читая первые и последние строки, что не так с плохим примером.
Одно утверждение на строку
Несмотря на то, что некоторые составные операторы, такие как списочные выражения, допускаются и ценятся за их краткость и выразительность, использование двух разделенных операторов в одной строке кода является плохой практикой.
Плохо
Хорошо
Аргументы функции
Аргументы могут быть переданы в функции четырьмя различными способами.
Программист должен написать функцию, чтобы определить, какие аргументы являются позиционными аргументами, а какие — необязательными аргументами ключевых слов, и решить, использовать ли передовые методы передачи произвольных аргументов. Если следовать приведенному выше совету разумно, можно и приятно писать функции Python, которые:
Избегайте волшебной палочки
Мощный инструмент для хакеров, Python поставляется с очень богатым набором хуков и инструментов, позволяющих вам выполнять практически любые хитрые трюки. Например, можно выполнить каждое из следующих действий:
Тем не менее, все эти варианты имеют много недостатков, и всегда лучше использовать самый простой способ для достижения вашей цели. Основным недостатком является то, что читаемость сильно страдает при использовании этих конструкций. Многие инструменты анализа кода, такие как pylint или pyflakes, не смогут проанализировать этот «волшебный» код.
Мы считаем, что разработчик Python должен знать об этих почти безграничных возможностях, потому что это вселяет уверенность в том, что на пути не будет непроходимых проблем. Однако очень важно знать, как и, в частности, когда их не использовать.
Подобно мастеру кунг-фу, питонист знает, как убивать одним пальцем, и никогда не делать этого на самом деле.
Мы все ответственные пользователи
Как видно выше, Python допускает множество трюков, и некоторые из них потенциально опасны. Хорошим примером является то, что любой клиентский код может переопределять свойства и методы объекта: в Python нет ключевого слова «private». Эта философия, очень отличающаяся от языков с высокой степенью защиты, таких как Java, которые предоставляют множество механизмов для предотвращения любого неправильного использования, выражается высказыванием: «Мы все ответственные пользователи».
Это не означает, что, например, никакие свойства не считаются закрытыми и что правильная инкапсуляция невозможна в Python. Скорее, вместо того, чтобы полагаться на бетонные стены, возводимые разработчиками между их кодом и чужим, сообщество Python предпочитает полагаться на ряд соглашений, указывающих, что к этим элементам не следует обращаться напрямую.
Основное соглашение для частных свойств и деталей реализации заключается в добавлении префикса ко всем «внутренним элементам». Если клиентский код нарушает это правило и получает доступ к этим отмеченным элементам, любое неправильное поведение или проблемы, возникшие при изменении кода, являются ответственностью клиентского кода.
Использование этого соглашения приветствуется: любой метод или свойство, которые не предназначены для использования клиентским кодом, должны начинаться с подчеркивания. Это гарантирует лучшее разделение обязанностей и более легкую модификацию существующего кода; всегда будет возможно обнародовать частную собственность, но сделать публичную собственность частной может быть гораздо более сложной операцией.
Возвращение значения
Когда функция усложняется, нередко используют несколько операторов return внутри тела функции. Однако, чтобы сохранить четкое намерение и устойчивый уровень читабельности, желательно избегать возврата значимых значений из многих выходных точек в теле.
Существует два основных случая возврата значений в функцию: результат возврата функции, когда она была обработана нормально, и случаи ошибок, которые указывают на неправильный входной параметр, или любую другую причину, по которой функция не может завершить вычисление или задача.
Если вы не хотите вызывать исключения для второго случая, может потребоваться возврат значения, такого как None или False, указывающего, что функция не может работать правильно. В этом случае лучше вернуться, как только был обнаружен неправильный контекст. Это поможет сгладить структуру функции: весь код после оператора return-from-of-error может предполагать, что условие выполнено для дальнейшего вычисления основного результата функции. Наличие нескольких таких операторов возврата часто необходимо.
Однако, когда функция имеет несколько основных точек выхода для своего нормального хода, становится трудно отлаживать возвращаемый результат, поэтому может быть предпочтительнее сохранить одну точку выхода. Это также поможет выделить некоторые пути кода, а несколько точек выхода являются вероятным признаком того, что такой рефакторинг необходим.
Идиомы
Хотя обычно есть один — и предпочтительно только один — очевидный способ сделать это; способ писать идиоматические коды Python могут быть неочевидными для начинающего Python. Таким образом, хорошие идиомы должны быть осознанно приобретены.
Ниже приведены некоторые распространенные идиомы Python:
Распаковка
Если вы знаете длину списка или кортежа, вы можете назначить имена его элементам при распаковке. Например, поскольку enumerate() будет предоставлять кортеж из двух элементов для каждого элемента в списке:
Вы также можете использовать это для замены переменных:
Вложенная распаковка тоже работает:
Создать игнорируемую переменную
Если вам нужно что-то назначить (например, в распаковке ), но вам не понадобится эта переменная, используйте __ :
Многие руководства по стилю Python рекомендуют использовать одно подчеркивание « _ » для одноразовых переменных, а не двойное подчеркивание « __ », рекомендованное здесь.Проблема заключается в том, что « _ » обычно используется в качестве псевдонима для gettext() функции, а также в интерактивном приглашении для хранения значения последней операции.Вместо этого использование двойного подчеркивания является столь же понятным и почти таким же удобным, и исключает риск случайного вмешательства в любой из этих других случаев использования.
Создайте список длины N того же самого
Используйте * оператор списка Python :
Создание списка длины N списков
Поскольку списки являются изменяемыми, * оператор (как указано выше) создаст список из N ссылок на один и тот же список, что вряд ли вам нужно. Вместо этого используйте понимание списка:
Примечание: используйте range () вместо xrange () в Python 3.
Создать строку из списка
Распространенная идиома для создания строк — использовать str.join() пустую строку.
Это установит значение переменной word в «spam». Эта идиома может применяться к спискам и кортежам.
Поиск предмета в коллекции
Иногда нам нужно искать в коллекции вещей. Давайте рассмотрим два варианта: списки и наборы.
Возьмите следующий код для примера:
Из-за этих различий в производительности часто рекомендуется использовать наборы или словари вместо списков в случаях, когда:
Для небольших коллекций или коллекций, в которых вы не часто будете искать, дополнительное время и память, необходимые для настройки хэш-таблицы, часто будут больше, чем время, сэкономленное благодаря улучшенной скорости поиска.
Дзен питона
Соглашения PEP8
Вот некоторые соглашения, которым вы должны следовать, чтобы сделать ваш код легче для чтения.
Проверьте, равна ли переменная постоянной
Вам не нужно явно сравнивать значение с True, None или 0 — вы можете просто добавить его в оператор if. См. Проверка истинности значения для получения списка того, что считается ложным.
Плохо :
Хорошо :
Доступ к элементу словаря
Плохо :
Хорошо :
Короткие способы манипулирования списками
Постижения списков предоставляют мощный и лаконичный способ работы со списками.
Выражения генератора следуют почти тому же синтаксису, что и списки, но возвращают генератор вместо списка.
Создание нового списка требует больше работы и использует больше памяти. Если вы просто собираетесь пройтись по новому списку, используйте вместо этого итератор.
Плохо :
Хорошо :
Используйте списки, когда вам действительно нужно создать второй список, например, если вам нужно использовать результат несколько раз.
Если ваша логика слишком сложна для понимания короткого списка или выражения генератора, рассмотрите возможность использования функции генератора вместо возврата списка.
Хорошо :
Никогда не используйте списочное понимание только для его побочных эффектов.
Плохо :
Хорошо :
Фильтрация списка
Плохо :
Никогда не удаляйте элементы из списка, пока вы просматриваете его.
Не делайте несколько проходов по списку.
Хорошо :
Используйте понимание списка или выражение генератора.
Возможные побочные эффекты изменения исходного списка
Изменение исходного списка может быть рискованным, если на него ссылаются другие переменные. Но вы можете использовать назначение срезов, если вы действительно хотите это сделать.
Изменение значений в списке
Плохо :
Помните, что назначение никогда не создает новый объект. Если две или более переменных ссылаются на один и тот же список, изменение одной из них изменит их все.
Хорошо :
Безопаснее создать новый объект списка и оставить оригинал в покое.
Используйте enumerate() счетчик вашего места в списке.
Читать из файла
Используйте синтаксис для чтения из файлов. Это автоматически закроет файлы для вас. with open
Плохо :
Хорошо :
Продолжение строки
Когда логическая строка кода длиннее допустимого предела, вам необходимо разбить ее на несколько физических строк. Интерпретатор Python объединяет последовательные строки, если последний символ строки является обратной косой чертой. Это полезно в некоторых случаях, но, как правило, его следует избегать из-за его хрупкости: пробел, добавленный в конец строки после обратной косой черты, нарушит код и может привести к неожиданным результатам.
Лучшее решение — использовать круглые скобки вокруг ваших элементов. Оставленный с незакрытой круглой скобкой в конце строки, интерпретатор Python присоединится к следующей строке, пока круглые скобки не будут закрыты. То же самое относится и к фигурным и квадратным скобкам.
Плохо :
Хорошо :
Однако чаще всего разделение длинной логической строки является признаком того, что вы пытаетесь сделать слишком много вещей одновременно, что может ухудшить читабельность.