PEP 8 - руководство по написанию кода на Python | Python 3

Следуйте правилам PEP 8 для повышения читаемости и единообразия своего Python-кода. Это не просто рекомендации, а гарантия, что ваши программы будут понятными и поддерживаемыми.

Максимальная длина строки - 79 символов. Это существенно улучшает восприятие кода на экране и предотвращает лишние горизонтальные скроллирования. Не допускайте строк, превышающих 79 символов.

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

Используйте правильные имена переменных. Используйте имена, описывающие задачи переменных (например, total_price вместо t). Используйте нижнее подчеркивание (snake_case) для имён функций, переменных и классов.

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

PEP 8 - руководство по написанию кода на Python 3

Применяйте отступы в 4 пробела. Не используйте табуляцию.

Используйте строчные имена для переменных и функций (например, `my_variable`, `calculate_sum`).

Для констант используйте верхний регистр с подчеркиванием (например, `MAX_VALUE`).

Длина строки кода не должна превышать 79 символов. Если строка длиннее - используйте переносы.

Используйте правильные имена для файлов: имена файлов имеют только строчные буквы и подчеркивания (например, `my_module.py`).

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

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

Выбирайте информативные имена переменных, отражающие их назначение.

Следуйте стандарту именования для импортируемых модулей: используйте короткие имена (например, `import math` вместо `import math_module`).

Используйте docstrings для описания функций и классов. Docstrings должны быть понятными и соответствовать правилам PEP 257.

Форматирование отступов и переносов строк

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

def функция(параметр1, параметр2):
print("Это сообщение")
if параметр1 > 10:
print("Параметр больше 10")
print("Далее код")

def функция(параметр1, параметр2):
print("Это сообщение")
if параметр1 > 10:
print("Параметр больше 10")
print("Далее код")

Не используйте табуляцию для отступов.

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

результат = очень_длинное_выражение_переменных_и_функций_с_множеством_символов(
переменная_1,
переменная2,
переменная_3
)

результат = очень_длинное_выражение_переменных_и_функций_с_множеством_символов(
переменная_1,
переменная_2,
переменная_3
)

Для вложенных конструкций и длинных выражений используйте переносы строк.

Вложенные конструкции:

if x > 10 and y < 5:

действие1()

дейстие2()

Длинные выражения:

длинное_сложное_выражение = очень_длинный_вызов_функции(аргумент1, аргумент2,

аргумент3, еще_аргумент)

Следите за согласованностью.

Именование переменных, функций и классов

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

Для классов используйте CamelCase: MyClass.

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

Примеры:

• Неправильно: myVariable, CalculateSum, maxValue
• Правильно: my_variable, calculate_sum, MAX_VALUE, MyClass

Исключение: имена модулей (файлов) записываются в нижнем регистре без подчёркивания.

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

Например, лучше total_price, чем price_of_order.

Работа с комментариями и документацией

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

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

• Пример плохого комментария: # присваиваем значение переменной a
• Пример хорошего комментария: # Вычисляем сумму первых n натуральных чисел

Документация (документационные строки) описывает функцию, класс или метод.

• Используйте тройные кавычки """ """ для многострочных строк.
• Первая строка документации (docstring) – это краткое описание.

def вычислить_сумму(n):
"""Вычисляет сумму первых n натуральных чисел."""
return n * (n + 1) // 2

Советы по оформлению документации:

1. Описание должно быть полным и понятным.
2. Используйте правильную грамматику и пунктуацию.
3. Укажите входные и выходные параметры.
4. Примеры использования могут дополнить документацию.

Примеры использования docstring

class Точка:
"""Класс для представления точки на плоскости."""
def __init__(self, x, y):
"""Инициализирует точку."""
self.x = x; self.y = y
def показать_координаты(self):
print(f"Координаты: ({self.x}, {self.y})")

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

Обработка ошибок и исключений

Используйте операторы try...except для обработки ожидаемых ошибок. Разработайте код, который может справиться с потенциальными проблемами, используя блок try для кода, который может вызвать ошибку, и блок except для обработки специфических исключений (например, FileNotFoundError, ValueError).

Будьте конкретны в обработке исключений. Не используйте общее исключение except Exception. Это снижает читабельность и затрудняет отладку. Обрабатывайте только те типы ошибок, которые вы ожидаете, и используйте informative messages в блоке except. Пример:

try:
with open('myfile.txt', 'r') as file:
content = file.read()
except FileNotFoundError:
print("Ошибка: файл myfile.txt не найден.")
except Exception as e:
print(f"Произошла непредвиденная ошибка: {e}")

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

Используйте логирование для документирования ошибок. Вместо print() для сообщений об ошибках используйте модуль logging. Это даст более богатую информацию о происхождении ошибок и поможет проводить анализ проблем.

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

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

Использование пустых строк и разделение кода на блоки

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

Пример:

def моя_функция(параметр1, параметр2):
# Блок кода для обработки параметр1
результат = параметр1 + параметр2
return результат
# Пустая строка отделяет функцию от остального кода
def другая_функция():
# Код другой функции
print("Это другая функция")
# Пустая строка отделяет эту функцию от остального кода
if __name__ == "__main__":
# Код основной программы
вызов_функции = моя_функция(5, 3)
print(вызов_функции)

Рекомендации по разделению на блоки:

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

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

Выбор имен файлов и импортов

Имена файлов должны быть короткими, но информативными. Используйте нижний регистр и подчеркивания, например, utils.py, data_processing.py.

Для импорта модулей используйте абсолютные импорты или относительные импорты, когда это целесообразно.

• Абсолютные импорты:
  • import my_module
  • from my_package.submodule import function
  • Рекомендуются для лучшей предсказуемости.
• Относительные импорты:
  • from . import module (импорт из текущей директории)
  • from ..utils import function (импорт из родительской директории)
  • Используйте с осторожностью, чтобы избежать ошибок, проверьте структуру проекта.

Избегайте длинных цепочек импортов, например, from my_package.submodule.nested_module import function. Делайте импорт модулей непосредственно, если это возможно.

Структура пакета должна отражать структуру проекта и быть иерархичной, используя точки для разграничения, например, my_module, my_package/data или my_package/utils.

1. Если модуль маленький (одна функция), не выделяйте его в отдельный файл.
2. Если модуль большой (несколько функций), создайте отдельный файл для него.
3. Старайтесь не импортировать всё сразу из модуля (from module import *). Импортируйте нужные переменные, функции или классы явно.

Имена пакетов и модулей должны быть именами существительных или нарицательных, например, database_utils, data_loading. Не используйте слишком длинные имена.

Вопрос-ответ:

Какие конкретные правила PEP 8 касаются именования переменных и функций?

PEP 8 рекомендует использовать имена переменных и функций в нижнем регистре, разделяя слова символом подчеркивания. Например, `my_variable` и `calculate_sum`. Важно согласовывать стиль именования внутри проекта. Также PEP 8 определяет, как именовать классы – с использованием Верблюжьего регистра (например, `MyClass`). Это придаёт коду читабельность и позволяет легко отличать переменные, функции и классы друг от друга.

Как PEP 8 помогает улучшить читаемость кода?

PEP 8 определяет правила форматирования кода, ориентированные на читаемость. Среди них – использование отступов (обычно 4 пробела), правильное размещение пробелов вокруг операторов, разбиение длинных строк кода на несколько строчек. Эти правила делают код более наглядным, позволяя легче следить за логикой программы. Также, согласованное применение правил существенно упрощает понимание кода другим разработчикам, которые работают с этим проектом. Это предотвращает путаницу и ошибки при последующей работе с кодом, когда его разрабатывает не автор исходного кода.

Нужно ли строго придерживаться всех правил PEP 8?

PEP 8 – это руководство, а не строгая инструкция. Не нужно слепо копировать каждое правило. Главное – соответствовать стилю, принятому в команде или проекте. Важно, чтобы код был понятным и последовательным. В некоторых случаях, незначительное отклонение от PEP 8 может не повлиять на функциональность, но сохранение согласованности стиля важна для максимальной читаемости кода. Выбирая правила форматирования, важно учитывать практическую значимость этих правил, а не только формальное соответствие.

Какие инструменты могут помочь в соблюдении рекомендаций PEP 8?

Есть несколько полезных инструментов для проверки кода на соответствие стилю PEP 8. Например, `flake8` – это популярный инструмент, который анализирует код и выявляет нарушения PEP 8, а также другие предостерегающие ошибки. Также существуют IDE (среды разработки), у которых есть встроенная поддержка PEP 8. Это автоматизирует процесс проверки кода и позволяет легко обнаруживать и исправлять нарушения, что значительно облегчает задачу повышения качества кода.