Комментарии
Комментарии — это важная часть любого проекта, потому что с их помощью можно понять, как работает код и какие особенности он имеет. Программисты использую комментарии не только для того, чтобы другие специалисты могли понять код, но и чтобы самим не забыть, как и зачем они реализовали те или иные функции.
Комментарии должны отражать суть кода, а не противоречить ему. Если код по какой-то причине изменяется, комментарии также необходимо изменить.
Все комментарии должны быть законченными предложениями, и если первое слово не является идентификатором, то оно должно начинаться с заглавной буквы.
Все комментарии должны быть написаны на английском языке, даже если программисты не из англоговорящей страны и на данный момент над проектом работают не англоговорящие программисты.
Комментарии можно писать не на английском, если вы уверены на 120%, что этот код никогда не будут смотреть люди не говорящие на вашем языке.
Блочные комментарии
Блочные комментарии используются, когда необходимо объяснить действий какого-либо блока кода. Как правило, такие комментарии размещаются над блоком кода на отдельной строке.
# Этот код делает что-то очень интересное a = 5 b = 10 a = b - a + a
Комментарии «в строке»
Это комментарии, которые объясняют действия строки кода и пишутся в той же строке, что и код. Они должны отделяться от кода не менее чем двумя пробелами.
Такие комментарии не рекомендуется использовать, потому что в большинстве случаев они объясняют очевидные вещи и не несут никакой практической пользы.
a = a / 2 # Деление числа на два
Однако в некоторых случаях они могут быть полезны, когда настоящее назначение строки не очевидно:
a = a / 2 # Получение середины экрана
Строки документации
Все открытые модули, функции, классы и их составляющие должны документироваться. Это правило не относится к приватным методам, однако между строкой с «def» и телом метода можно написать комментарий, который описывает назначение метода.
Более подробно про соглашение о документации рассказано в PEP 257. Кавычки, показывающие окончания строк документации, должны переносится на новую строку.
"""Speed determination. Keyword arguments: distance -- distance traveled in meters time -- time in seconds (default 1) """
Однако, если документация состоит из одной строки, то кавычки не переносятся.
"""Some info about something."""
Пробелы в выражениях и утверждениях
«Разреженное лучше плотного», — Дзен Python.
Пробелы могут быть очень полезны в выражениях и операторах при правильном использовании. Если пробелов недостаточно, могут возникнуть трудности при чтении кода: он сливается в сплошное полотно. Если пробелов слишком много, может быть сложно визуально объединить связанные между собой операторы.
Пробелы вокруг двоичных операторов
Следующие бинарные операторы нужно окружать пробелами с обеих сторон:
- Операторы присваивания (=, + =, — = и т. д.);
- Сравнения (==,! =,>, <.> =, <=) и (is, is not, in, not in);
- Логические операторы (and, not, or).
Замечание. Когда = используется для присвоения значения по умолчанию аргументу функции, не окружайте его пробелами.
# Рекомендуется
def function(default_parameter=5):
# ...
# Не рекомендуется
def function(default_parameter = 5):
# ...
Когда в инструкции содержится более одного оператора, добавление одного пробела до и после каждого оператора может привести к путанице. Вместо этого лучше добавлять пробелы только вокруг операторов с самым низким приоритетом, особенно при выполнении математических манипуляций. Вот пара примеров:
# Рекомендуется y = x**2 + 5 z = (x+y) * (x-y) # Не рекомендуется y = x ** 2 + 5 z = (x + y) * (x - y)
Вы также можете применить это к операторам с несколькими условиями:
# Не рекомендуется
if x > 5 and x % 2 == 0:
print('x больше 5 и чётное!')
В приведенном выше примере оператор имеет самый низкий приоритет. Поэтому будет более ясным следующее выражение :
# Рекомендуется
if x>5 and x%2==0:
print('x больше 5 и чётное!')
Вы можете выбрать наиболее понятный вариант, с оговоркой, что будете использовать одинаковое количество пробелов по обе стороны от оператора.
Следующее недопустимо:
# Никогда так не делайте!
if x >5 and x% 2== 0:
print('x больше 5 и чётное!')
В срезах двоеточия действуют как бинарные операторы. Следовательно, применяются правила, изложенные в предыдущем разделе, и с каждой стороны должно быть одинаковое количество пробелов. Допустимы следующие варианты оформления срезов списка:
list # Двоеточие - оператор с наименьшим приоритетом list # В расширенном срезе оба двоеточия следует # обособить одинаковым количеством пробелов list list # Если не указан параметр среза, опускается и пробел list
Таким образом, вы должны окружить большинство операторов пробелами. Однако у этого правила есть некоторые оговорки, например, в аргументах функций или когда используется сразу несколько операторов.
Когда избегать добавления пробелов
В некоторых случаях добавление пробелов может затруднить чтение кода. Слишком много пробелов может сделать код слишком разреженным и трудным для понимания. PEP 8 дает четкое описание примеров, когда пробелы неуместны.
Самое важное место, где следует избегать пробелов, – это конец строки. Это называется завершающим пробелом (trailing whitespace)
Такой пробел невидим и может приводить к ошибкам, которые трудно отследить.
В следующем списке перечислены некоторые случаи, когда вам не следует добавлять пробелы:
Сразу после открывающей скобки и непосредственно перед закрывающей:
# Рекомендуется my_list = # Не рекомендуется my_list =
Для отделения запятой, точки с запятой или двоеточия:
x = 5 y = 6 # Рекомендуется print(x, y) # Не рекомендуется print(x , y)
Перед открывающей скобкой, с которой начинается список аргументов вызова функции:
def double(x):
return x * 2
# Рекомендуется
double(3)
# Не рекомендуется
double (3)
Перед открывающей скобкой, с которой начинается индекс или срез:
# Рекомендуется list # Не рекомендуется list
Между запятой и закрывающей круглой скобкой:
# Рекомендуется tuple = (1,) # Не рекомендуется tuple = (1, )
Чтобы выровнять операторы присваивания:
# Рекомендуется var1 = 5 var2 = 6 some_long_var = 7 # Не рекомендуется var1 = 5 var2 = 6 some_long_var = 7
Убедитесь, что в вашем коде нет завершающих пробелов. Есть и другие случаи, когда PEP 8 не рекомендует добавлять лишние пробелы, например, непосредственно после открывающей и перед закрывающей скобкой.
Почему табуляция в Питоне так важна?
Что такое отступ? Говоря простыми словами, это просто добавление пробела перед определенным оператором.
Отступы — важная концепция языка Питон, так как без правильного их оформления в итоге программист получит ошибку типа , код при этом не будет скомпилирован.
Многим программистам жесткое соблюдение отступов может показаться избыточной мерой. Однако именно из-за строго соблюдения правил форматирования, код на Python — чистый, понятный и аккуратный. Отсюда следующие плюсы :
- Не нужно проверять, не потерялась ли лишняя скобка;
- Читать такой код удобнее (по «Философии Python» — читаемость имеет значение);
- Легче работать со сторонними библиотеками;
- Код вашего коллеги будет максимально похож на ваш код.
Чтобы понять, насколько это важно, можно представить ситуацию, когда в книге удалить все номера страниц, в результате чего нельзя будет понять, где продолжать чтение. Без использования indent-отступа интерпретатор Python не сможет определить, какой оператор необходимо выполнять следующим, что относится к разным блокам кода
В результате и возникает исключение типа .
В большинстве других языков, таких как семейство C, Java и прочих для оформления блоков используются фигурные скобки, в Питоне — отступы, для создания которых обычно используются пробелы. Все команды, отделенные от начала строки одним и тем же расстоянием, принадлежат к одному и тому же блоку. Если в нем выделяется еще один блок — используется еще один отступ вправо, и так далее. Рассмотрим это на примере:
По умолчанию в Python используется 4 пробела в качестве отступа
Однако программист может использовать и другое их количество, но не менее одного.
Имена
В документе РЕР8 для различных элементов языка предлагается свой стиль имен. Благодаря этому можно легко определить в процессе чтения кода, какому типу соответствует то или иное имя:
- Имена функций, переменных и атрибутов должны следовать формату lowercase_underscore (нижний регистр букв, разделение слов символами подчеркивания) .
- Имена защищенных атрибутов экземпляра должны следовать _leading_underscore (один символ подчеркивания в начале).
- Имена закрытых атрибутов экземпляра должны следовать формату __leading_underscore (два символа подчеркивания в начале).
- Имена классов и исключений должны следовать формату CapitalizeWord (каждое слово начинается с прописной буквы).
- Константы уровня модуля должны записываться в формате ALL_CAPS (все буквы прописные, в качестве разделителя используется символ подчеркивания).
- В определениях методов экземпляров классов в качестве имени первого параметра следует всегда указывать self (это имя ссылается на текущий объект).
- В определениях методов классов в качестве имени первого параметра следует всегда указывать cls (это имя ссылается на текущий класс).
Зачем нужен PEP 8
“Читаемость имеет значение”, — Дзен Python
PEP 8 существует для улучшения читаемости кода Python. Но почему так важна удобочитаемость? Почему написание читаемого кода является одним из руководящих принципов языка Python?
Как сказал Гвидо ван Россум: «Код читают гораздо чаще, чем пишут». Вы можете потратить несколько минут или целый день на написание фрагмента кода для аутентификации пользователя. В дальнейшем вам не придётся его писать. Но перечитывать его вы точно будете. Этот фрагмент кода может остаться частью проекта, над которым вы работаете. Каждый раз, возвращаясь к этому файлу, вам нужно будет вспомнить, что делает этот код и зачем вы его написали. Поэтому удобочитаемость имеет большое значение.
Если вы новичок в Python, возможно, вам уже через несколько дней или недель будет трудно вспомнить, что делает фрагмент кода. Но если вы следуете PEP 8, вы можете быть уверены, что правильно назвали свои переменные . Вы будете знать, что добавили достаточно пробелов, чтобы обособить логические шаги. Вы также снабдили свой код отличными комментариями. Все это сделает ваш код будет более читабельным, а значит, к нему будет легче вернуться. Следование правилам PEP 8 для новичка может сделать изучение Python гораздо более приятной задачей.
Следование PEP 8 особенно важно, если вы претендуете на должность разработчика. Написание понятного, читаемого кода свидетельствует о профессионализме
Это скажет работодателю, что вы понимаете, как правильно структурировать свой код.
Работая над проектами, вам, скорее всего, придется сотрудничать с другими программистами
Здесь, опять же, очень важно писать читаемый код. Другие люди, которые, возможно, никогда раньше не встречали вас и не видели ваш стиль программирования, должны будут прочитать и понять ваш код
Наличие руководящих принципов, которым вы следуете и которые знаете, облегчит другим чтение вашего кода.
2 ответа
Лучший ответ
Вы должны прочитать ошибку компиляции. Там написано, что в строке 33 ошибка. Строка 33:
Оператор возврата тоже должен иметь отступ. Так должно быть:
Т. е. оператор return должен иметь такой же отступ, как и функция.
Тем не менее, в этом случае я не думаю, что вам даже нужно возвращать заявление. Почему бы вам просто не удалить его и посмотреть, работает ли ваш код так, как вы ожидаете? Я думаю, что так и будет.
РЕДАКТИРОВАТЬ:
Автор прокомментировал ниже, что они пробовали различные суммы отступов для , и ни один из них не работал. Причина этого в том, что все остальное в функции было слишком много отступов. Каждый слой должен иметь отступ с одним отступом, и стандарт обычно равен 1 отступу = 1 табуляция или 4 пробела. Итак, это:
… должно было быть так:
Примечание: 1. Каждый слой кода имеет отступ на определенное количество. Первый слой, например, , имеет отступ в 4 пробела. Тогда вещи внутри оператора имеют отступ 8 = 4 * 2 пробела. и т.п. 2. Предполагается, что оператор происходит не в выражении , а в основной части кода, поэтому он имеет отступ с той же величиной, что и основная часть кода.
Я был прав, когда сказал, что вам вообще не нужно выражение , но стоит объяснить, почему вы сначала получили эту ошибку, даже если попытались сделать отступ в этом выражении, поскольку вы, вероятно, столкнетесь с этим в будущее. Фактически, вы можете получить такую ошибку, если вы используете табуляцию для отступа одной строки и 4 пробела для отступа другой! Вам нужно выбрать правило для отступа, а затем придерживаться его. Надеюсь это поможет.
Max von Hippel
28 Июл 2019 в 15:49
Python — это язык с ограниченным отступом, который в простом английском языке в основном означает, что он использует отступ, чтобы определить, какая строка кода принадлежит какому уровню области.
Например, когда python читает ваш код, он проверяет уровень отступа, чтобы определить, принадлежит ли эта строка и является ли она циклом или функцией или чем-то подобным.
Вы можете узнать больше о здесь
1
Vipul Bhardwaj
28 Июл 2019 в 15:26
Комментарии
Комментарии, которые противоречат коду, хуже, их отсутсвие. Всегда исправляйте комментарии, когда меняете код!
Комментарии
должны представлять собой законченными предложениями. Если комментарий — фраза
или предложение, первое слово должно быть написано с большой буквы, если
только это не имя переменной, которая начинается с маленькой буквы
(никогда не изменяйте регистр переменной!).
Если комментарий
короткий, можно не ставить точку в конце предложения. Блок комментариев
обычно состоит из одного или более абзацев, составленных из полноценных
предложений, поэтому каждое предложение должно оканчиваться точкой.
Ставьте два пробела после точки в конце предложения.
Если вы пишете по-английски, не забывайте о книге “Elements of style” Странка и Уайта. Эта книга является эталонным руководством по правильному написанию текстов на
английском языке.
Программистам,
которые не говорят на английском языке следует писать комментарии
на английском. За исключением случаев, когда Вы на 126% уверены, что Ваш код никогда не будут читать люди не знающие вашего родного языка.
Блоки комментариев
Блок
комментариев обычно объясняет код (весь, или только некоторую часть),
идущий после блока, и должен иметь тот же отступ, что и сам код.
Каждая
строчка такого блока должна начинаться с символа # и одного пробела
после него.
Абзацы внутри блока комментариев разделяются строкой, состоящей только из одного символа #.
«Встрочные» комментарии
Старайтесь реже использовать подобные комментарии.
Такой
комментарий находится в той же строке, что и инструкция. «Встрочные»
комментарии должны отделяться как минимум двумя пробелами от
самой инструкции. И должны начинаться с символа # и одного пробела.
Если комментарии объясняют очевидное — они не нужны, т.к. только отвлекают от чтения кода
Пример как писать не нужно:
x = x + 1 # Increment x
Строки документации
Пишите
документацию для всех public модулей, функций, классов, методов. Для не-public методов cтроки документации необязательны, но лучше описать, что делает метод. Комментарий нужно писать после строки с def.
PEP 257
объясняет, как правильно писать документацию
Очень
важно, чтобы закрывающие кавычки стояли на отдельной строке. А еще
лучше, если перед ними будет ещё и пустая строка.
Пример:
-
"""Return a foobang Optional plotz says to frobnicate the bizbaz first. """
-
Для однострочной документации можно оставить закрывающие кавычки на той же строке.
Пробелы
В языке Python пробелы имеют синтаксическое значение. Особое значение Pythоn-программисты придают влиянию пробелов на удобочитаемость кода.
- Используйте пробелы, а не символы табуляции для создания отступов.
- Используйте по 4 пробела для каждого уровня синтаксически значимых отступов.
- Длина строк не должна превышать 79 символов.
- Дополнительные строки, являющиеся продолжением длинных выражений, должны выделяться четырьмя дополнительными пробелами сверх обычного их количества для отступов данного уровня.
- Между определениями функций и классов в файлах следует вставлять две пустые строки.
- Между определениями методов в классах следует вставлять одну пустую строку.
- Не окружайте пробелами индексы элементов списков вызовы функций и операторы присваивания значений именованным аргументам.
- Помещайте по одному и только одному пробелу до и после оператора присваивания.
Циклы
9.1 Циклы по спискам
Если нам необходимо в цикле пройти по всем элементам списка, то хорошим тоном (да и более читаемым) будет такой способ:
Хорошо
И хотя бывалые программисты или просто любители C могут использовать и такой код, это моветон.
Плохо
А если нужно пройти по списку задом наперед, то лучше всего использовать метод reversed:
Хорошо
Вместо того чтобы писать избыточный код, который и читается-то не очень внятно.
Плохо
9.2 Циклы по списку чисел
Если есть необходимость пройти в цикле по ряду чисел, то метод range будет намного приемлемее, как минимум потому, что этот метод потребляет намного меньше памяти, чем вариант в блоке «Плохо». А представьте, что у вас ряд из трёх миллиардов последовательных чисел!
Хорошо
Плохо
9.3 Циклы по спискам с индексами
Метод enumerate позволяет получить сразу индекс и значение из списка, что, во-первых, предоставляет множество возможностей для дальшнейшего проектирования, а во-вторых, такой код легче читается и воспринимается.
Хорошо
Плохо
Соглашения по именованию
Соглашения по именованию переменных в python немного туманны, поэтому их список никогда не будет полным — тем не менее, ниже мы приводим список рекомендаций, действующих на данный момент. Новые модули и пакеты должны быть написаны согласно этим стандартам, но если в какой-либо уже существующей библиотеке эти правила нарушаются, предпочтительнее писать в едином с ней стиле.
Главный принцип
Имена, которые видны пользователю как часть общественного API должны следовать конвенциям, которые отражают использование, а не реализацию.
Описание: Стили имен
Существует много разных стилей. Поможем вам распознать, какой стиль именования используется, независимо от того, для чего он используется.
Обычно различают следующие стили:
- b (одиночная маленькая буква)
- B (одиночная заглавная буква)
- lowercase (слово в нижнем регистре)
- lower_case_with_underscores (слова из маленьких букв с подчеркиваниями)
- UPPERCASE (заглавные буквы)
- UPPERCASE_WITH_UNDERSCORES (слова из заглавных букв с подчеркиваниями)
- CapitalizedWords (слова с заглавными буквами, или CapWords, или CamelCase). Замечание: когда вы используете аббревиатуры в таком стиле, пишите все буквы аббревиатуры заглавными — HTTPServerError лучше, чем HttpServerError.
- mixedCase (отличается от CapitalizedWords тем, что первое слово начинается с маленькой буквы)
- Capitalized_Words_With_Underscores (слова с заглавными буквами и подчеркиваниями — уродливо!)
Ещё существует стиль, в котором имена, принадлежащие одной логической группе, имеют один короткий префикс. Этот стиль редко используется в python, но мы упоминаем его для полноты. Например, функция os.stat() возвращает кортеж, имена в котором традиционно имеют вид st_mode, st_size, st_mtime и так далее. (Так сделано, чтобы подчеркнуть соответствие этих полей структуре системных вызовов POSIX, что помогает знакомым с ней программистам).
В библиотеке X11 используется префикс Х для всех public-функций. В python этот стиль считается излишним, потому что перед полями и именами методов стоит имя объекта, а перед именами функций стоит имя модуля.
В дополнение к этому, используются следующие специальные формы записи имен с добавлением символа подчеркивания в начало или конец имени:
-
_single_leading_underscore: слабый индикатор того, что имя используется для внутренних нужд. Например, from M import * не будет импортировать объекты, чьи имена начинаются с символа подчеркивания.
-
-
single_trailing_underscore_: используется по соглашению для избежания конфликтов с ключевыми словами языка python, например:
Tkinter.Toplevel(master, class_='ClassName')
-
__double_leading_underscore: изменяет имя атрибута класса, то есть в классе FooBar поле __boo становится _FooBar__boo.
-
__double_leading_and_trailing_underscore__ (двойное подчеркивание в начале и в конце имени): магические методы или атрибуты, которые находятся в пространствах имен, управляемых пользователем. Например, __init__, __import__ или __file__. Не изобретайте такие имена, используйте их только так, как написано в документации.
Генерация списков, словарей и множеств
Генерация списков, словарей и множеств командами в одну строку — наиболее мощные и характерные фичи языка Python. Всё это великолепие работает и с форматированными строками. Вот список из форматированных строк, созданный на основе другого списка:
Форматированная строка может содержать и генератор списка, с этим проблем нет, — тогда она выдаст строку, состоящую из вычисленного списка, а не из команды генератора.
Со словарями и множествами дело обстоит чуть иначе — в основном из-за наличия фигурных скобок. Поэтому для того, чтобы строка была в виде словаря, а не в виде текста генератора, надо добавлять пробелы между внутренними и внешними фигурными скобками.
Как проверить соответствие кода PEP 8
Чтобы убедиться, что ваш код соответствует PEP 8, необходимо многое проверить. Помнить все эти правила при разработке кода может быть непросто. Особенно много времени уходит на приведение прошлых проектов к стандарту PEP 8. К счастью, есть инструменты, которые помогут ускорить этот процесс.
Существует два класса инструментов, которые можно использовать для обеспечения соответствия PEP 8: линтеры и автоформаттеры.
Линтеры
Линтеры – это программы, которые анализируют код, помечают ошибки и предлагают способы их исправления. Они особенно полезны как расширения редактора, поскольку выявляют ошибки и стилистические проблемы во время написания кода.
Вот пара лучших линтеров для кода на Python:
pycodestyle
Это инструмент для проверки вашего кода на соответствие некоторым стилевым соглашениям в PEP8.
Установите pycodestyle с помощью pip:
$ pip install pycodestyle
Вы можете запустить pycodestyle из терминала, используя следующую команду:
$ pycodestyle code.py
Результат:
code.py:1:17: E231 missing whitespace after ',' code.py:2:21: E231 missing whitespace after ',' code.py:6:19: E711 comparison to None should be 'if cond is None:'
flake8
Это инструмент, который сочетает в себе отладчик, pyflakes и pycodestyle.
Установите flake8 с помощью pip:
$ pip install flake8
Запустите flake8 из терминала, используя следующую команду:
$ flake8 code.py
Пример вывода:
code.py:1:17: E231 missing whitespace after ',' code.py:2:21: E231 missing whitespace after ',' code.py:3:17: E999 SyntaxError: invalid syntax code.py:6:19: E711 comparison to None should be 'if cond is None:'
Замечание: Дополнительная строка в выводе указывает на синтаксическую ошибку.
Также доступны расширения для Atom, Sublime Text, и VIM.
От редакции Pythonist. Рекомендуем статью «Качество кода на Python: сравнение линтеров и советы по их применению».
Автоформаттеры
Автоформаттеры – это программы, которые автоматически реорганизуют ваш код для соответствия PEP 8. Одна из таких программ — . Она автоматически форматирует код для приведения его в соответствие с большинством правил PEP 8. Единственное, она ограничивает длину строки до 88 символов, а не до 79, как рекомендовано стандартом. Однако вы можете изменить это, добавив флаг командной строки, как в примере ниже.
Установите black с помощью pip. Для запуска требуется Python 3.6+:
$ pip install black
Его можно запустить из командной строки, как и в случае с линтерами. Допустим, вы начали со следующего кода, который не соответствует PEP 8, в файле с именем code.py:
for i in range(0,3):
for j in range(0,3):
if (i==2):
print(i,j)
Затем вы можете запустить следующую команду через командную строку:
$ black code.py reformatted code.py All done!
code.py будет автоматически приведён к следующему виду:
for i in range(0, 3):
for j in range(0, 3):
if i == 2:
print(i, j)
Если вы хотите изменить ограничение длины строки, можно использовать флаг :
$ black --line-length=79 code.py reformatted code.py All done!
Работа двух других автоформаттеров – autopep8 и yapf – аналогична работе black .
О том, как использовать эти инструменты, хорошо написано в статье Python Code Quality: Tools & Best Practices Александра ван Тол.
Перевод части статьи .
В следующих статьях цикла про PEP 8 читайте:
- Нейминг и размещение кода
- Комментарии, пробелы, выбор методов
Линтеры и автоформаттеры
Мы можем использовать линтеры и автоформаттеры, чтобы убедиться, что наш код совместим с PEP 8. Поговорим о них!
Линтеры
ЛИНТЕР анализируют наши программы и отмечают все имеющиеся у нас ошибки. Они дают нам советы, как исправить наши ошибки. Мы можем установить линтеры как расширения к нашим текстовым редакторам, что означает, что они будут отмечать ошибки при написании кода. Доступно множество различных линтеров Python. Давайте посмотрим на два самых популярных линтера:
Flake8
Flake8 является инструментом, который комбинаты pyflakes, pycodestyleи отладчик. Мы можем вызвать Flake8 из командной строки или через Python. Мы можем использовать Flake8 для проверки всего исходного кода или сузить область проверки, указав конкретные пути и каталоги, которые мы хотим просмотреть.
pycodestyle
pycodestyle — это инструмент, который проверяет наш код Python на соответствие некоторым соглашениям о стилях, изложенным в руководстве по стилю PEP 8. pycodestyleБиблиотека не проверяет все. Например, в настоящее время он не поддерживает проверки соглашений об именах, соглашений о строках документации или автоматического исправления. Доступны различные расширения и инструменты, которые могут проверить некоторые вещи, которые pycodestyle не может проверить.
Почему важно стандартизировать код?
На самом деле программисты проводят большую часть за анализом кода, а не за его написанием. Это происходит потому, что ничего не пишется с нуля. Берутся уже готовые и отлаженные решения, которые модифицируются под определенный проект. Кроме того, часто необходимо поддерживать уже существующие программы, код которых насчитывает сотни тысяч строк.
Если каждый программист будет писать код с разным стилем, то его анализ станет очень трудной задачей
Поэтому важно, чтобы Python-разработчики следовали определенным соглашениям, которые позволяют стандартизировать код, сделать его более понятным любому специалисту
Рекомендации по созданию красивого кода на Python не определяют стиль кода полностью. Поэтому программист может делать некоторые вещи на своё усмотрение, однако он всё ещё должен следовать тем указаниям, которые определены в стандарте.
Внутри команды разработчиков может выработаться особый стиль написания кода, который может в некоторых местах нарушать принятые соглашения. Это нередкая и допустимая ситуация, однако программист должен помнить, что если он уйдет из этой команды, ему придется заново переучиваться писать код в соответствии с принятыми стандартами.
Дзен питона
Также известен как PEP 20 , руководящие принципы для дизайна Python.
>>> import this The Zen of Python, by Tim Peters Beautiful is better than ugly. Explicit is better than implicit. Simple is better than complex. Complex is better than complicated. Flat is better than nested. Sparse is better than dense. Readability counts. Special cases aren't special enough to break the rules. Although practicality beats purity. Errors should never pass silently. Unless explicitly silenced. In the face of ambiguity, refuse the temptation to guess. There should be one-- and preferably only one --obvious way to do it. Although that way may not be obvious at first unless you're Dutch. Now is better than never. Although never is often better than *right* now. If the implementation is hard to explain, it's a bad idea. If the implementation is easy to explain, it may be a good idea. Namespaces are one honking great idea -- let's do more of those!
Некоторые примеры хорошего стиля Python см. На этих слайдах из группы пользователей Python .
Размещение кода
«Красивое лучше уродливого», — Дзен Python.
Расположение строк вашего кода играет огромную роль в его читабельности. В этом разделе вы узнаете, как добавлять отступы, чтобы улучшить читаемость кода. Вы также узнаете, как использовать ограничение в 79 символов в строке, рекомендованное в PEP 8.
Пустые строки
Вертикальные пробелы (т.е. пустые строки) могут значительно улучшить читаемость вашего кода. Код, который сливается в сплошной блок, сложно просматривать. Но слишком много пустых строк делают код очень разреженным, и читателю придется прокручивать его куда чаще, чем хотелось бы. Ниже приведены три основных правила использования вертикальных пробелов.
Окружайте функции и классы верхнего уровня двумя пустыми строками
Функции и классы верхнего уровня должны быть довольно самодостаточными и реализовывать отдельные части функциональности. Имеет смысл обособить их, добавив дополнительное пространство по вертикали, чтобы было ясно, что они разделены:
class MyFirstClass:
pass
class MySecondClass:
pass
def top_level_function():
return None
Разделяйте определения методов в классах одной пустой строкой
Внутри класса все функции связаны друг с другом. Рекомендуется оставлять между ними только одну строку:
class MyClass:
def first_method(self):
return None
def second_method(self):
return None
Используйте пустые строки внутри функций, чтобы показать четкие шаги
Иногда сложная функция должна выполнить несколько шагов до оператора . Чтобы помочь читателю понять логику внутри функции, бывает полезно оставлять пустую строку перед каждым новым шагом.
В приведенном ниже примере есть функция для вычисления дисперсии списка. Это двухэтапная задача, поэтому я обозначил каждый шаг, оставив между ними пустую строку. Перед оператором возврата также есть пустая строка. Это помогает читателю ясно увидеть, что возвращает функция:
def calculate_variance(number_list):
sum_list = 0
for number in number_list:
sum_list = sum_list + number
mean = sum_list / len(number_list)
sum_squares = 0
for number in number_list:
sum_squares = sum_squares + number**2
mean_squares = sum_squares / len(number_list)
return mean_squares - mean**2
Аккуратное использование вертикальных пробелов может значительно улучшить читаемость вашего кода. Оно помогает читателю с первого взгляда понять, как ваш код разбивается на разделы и как эти разделы соотносятся друг с другом.
Максимальная длина строки и разрыв строки
PEP 8 предлагает ограничение на длину строк в 79 символов. Такая длина позволяет открывать несколько файлов рядом друг с другом, а также избегать переноса строк.
Конечно, не все предложения возможно вместить в 79 или менее символов. В PEP 8 очерчивает способы написать длинное предложение, заняв несколько строк.
Если код заключен в круглые, квадратные или фигурные скобки, Python «поймет», что это одно предложение:
def function(arg_one, arg_two,
arg_three, arg_four):
return arg_one
Также, если невозможно дописать код в одну строку, вы можете использовать обратную косую черту для разрыва строк:
from mypkg import example1, \
example2, example3
Однако, если вы можете продолжить писать в одну строку, вам следует это сделать.
Если разрыв строки должен произойти около бинарных операторов, таких как и , он должен произойти перед оператором. Это правило происходит из математики. Математики согласны с тем, что прерывание перед бинарными операторами улучшает читаемость. Сравните следующие два примера.
Разрыв перед бинарным оператором:
# Рекомендуется
total = (first_variable
+ second_variable
- third_variable)
Вы можете сразу увидеть, какая переменная прибавляется или вычитается, поскольку оператор находится рядом с переменной, над которой выполняется операция.
Теперь давайте посмотрим на пример разрыва после бинарного оператора:
# Не рекомендуется
total = (first_variable +
second_variable -
third_variable)
Здесь сложнее разглядеть, какая переменная добавляется, а какая вычитается.
Прерывание строки перед бинарными операторами дает более читаемый код, поэтому PEP 8 это поощряет.
Если вы переходите на новую строку после бинарного оператора, но делаете так последовательно во всем документе (проекте), это по-прежнему соответствует PEP 8. Но всё же рекомендуется первый вариант.
Где положить скобок, кронштейн или скобок?
Для многострочных конструкций есть два основных варианта того, как правильно намерены данные.
1. Выровняйте закрывающуюся скобу с первым небеснепространным характером предыдущей линии :
# PEP 8 Compliant
age = {
'Alice': 24,
'Bob': 28,
'Ann': 26,
}
2. Совместите закрывающуюся скобу с первым символом, который запускает многострочную конструкцию :
# PEP 8 Compliant
age = {
'Alice': 24,
'Bob': 28,
'Ann': 26,
}
Оба пути отступа одинаково действительны Отказ Но обратите внимание, что в любом случае, открытие и закрывающие скобки (скобки, скобки) должны быть помещены в собственную линию. Так что следующее было бы нарушением стандарта PEP 8:
# NOT PEP 8 COMPLIANT
age = {'Alice': 24,
'Bob': 28,
'Ann': 26,
}
Причина в том, что как открывающие и закрывающие скобки (скобки, скобки) должны быть помещены в свою собственную линию.
Тем не менее, позволяет не размещать как открывающие и закрывающие скобки (скобки, скобки) в собственную линию – если аргументы или элементы выравниваются. Вот три совместимых примера PEP 8:
# PEP 8 Compliant
def f(argument_1, argument_2,
argument_3, argument_4):
None
# PEP 8 Compliant
def f(argument_1,
argument_2,
argument_3,
argument_4):
None
# PEP 8 Compliant
def f(argument_1, argument_2, argument_3, argument_4):
None
Хотя открытие и закрытие скобок не помещают в свои собственные строки, он по-прежнему PEP 8 соответствует тем, что аргументы выравниваются в первых двух примерах.
Следующий интерактивный код еще не готов. Требуется ваша сверхдержава отладки:
Упражнение : Отладка кода так, чтобы он запущен. Какой метод отступа является вашим предпочтительным?
