Стандарты и стиль Python-кода

Соблюдение стандартов сообщества гарантирует, что ваш код будет читаемым, предсказуемым и поддерживаемым. В экосистеме Python фундаментом являются "The Zen of Python" (Дзен Питона) и стандарт PEP 8.

PEP 8 — Официальный стиль написания кода

PEP 8 — это библия Python-программиста. Документ описывает, какие отступы ставить, как называть переменные и как расставлять пробелы.

Главные правила:

1. Отступы: Строго 4 пробела для каждого уровня вложенности (Табуляция запрещена).
2. Длина строки: Удерживайте длину строки до 79 символов (хотя современные стандартны форматера Black позволяют оставлять до 88 символов).
3. Пустые строки: Окружайте функции верхнего уровня и классы двумя пустыми строками \n\n. Методы внутри классов — одной строкой.
4. Импорты: Пишутся на отдельных строках. Группируются сверху вниз: системные библиотеки, сторонние пакеты, локальные файлы.
5. Именование:
   • Классы: CamelCase (PascalCase).
   • Функции и переменные: snake_case (строчные_слова_через_подчеркивание).
   • Константы: UPPER_CASE_SNAKE (заглавными буквами).

PEP 257 — Стандарт Docstrings

Докстринги (Docstrings) — это строки документации, которые пишутся в тройных кавычках сразу под объявлением функции, описывая суть её работы, параметры и возвращаемое значение. Существуют различные конвенции (Sphinx, Google, NumPy), самая популярная сегодня – Google Style.

def fetch_data(url: str, timeout: int = 10):
    """
    Скачивает данные с удаленного сервера.

    Args:
        url (str): Адрес сервера.
        timeout (int): Максимальное время ожидания.

    Returns:
        Сырые байты тела ответа.
    """
    pass

Автоматические Форматтеры (Современный подход)

Писать код по PEP 8 вручную — мука. В серьезных компаниях никто так не делает: разработчики используют автоматизированные утилиты-форматтеры.

Black

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

pip install black
black my_script.py

isort

Утилита isort автоматически сортирует ваши import-строки по алфавиту и группирует их.

pip install isort
isort my_script.py

Flake8 & Ruff (Линтеры)

Линтеры не изменяют ваш код (в отличие от форматтеров), они только "подсказывают" на ошибки: неиспользуемые импорты, забытые переменные, потенциальные баги.

• flake8: Классический золотой стандарт проверок.
• ruff: Сверхбыстрый инструмент написанный на Rust, объединяющий Flake8, Black, isort и десятки других плагинов в одну мгновенную утилиту. Наш выбор на 2024 год!

Принципы Чистого Кода (Clean Code)

1. Говорящие названия: Переменные должны отражать свой смысл (days_left вместо d).
2. Функции делают что-то одно: Если в названии функции есть слово "and" (и), возможно, она слишком громоздкая.
3. Раннее падение (Fail fast): Проверяйте типы параметров в начале функции и сразу кидайте исключение (raise ValueError), а не плодите 100 отступов оператором if.