Проверка читаемости, стиля, PEP 8, именования, структуры кода
Читаемость кода важнее хитрости. Код читается в 10 раз чаще, чем пишется.
Чек-листы систематизируют процесс code review и помогают не упустить важные аспекты:
| Проверяем | Хорошо | Плохо |
|---|---|---|
| Переменные | user_age, total_price | a, tmp, data |
| Функции | calculate_discount(), get_user_by_id() | calc(), get() |
| Классы | UserProfile, PaymentService | user, service |
| Константы | MAX_RETRY_COUNT, DEFAULT_TIMEOUT | max, default |
| Булевы | is_active, has_permission | flag, status |
Правила именования:
if status == 3 → if status == ORDER_SHIPPEDgeneration_timestamp вместо gen_tsthe, info, data, managerПризнаки хорошей функции:
# ❌ Плохо: функция делает слишком много
def process_user(user_id):
user = db.query("SELECT * FROM users WHERE id = ?", user_id)
if user:
data = parse_user_data(user)
result = calculate_metrics(data)
formatted = format_output(result)
save_to_cache(user_id, formatted)
send_notification(user_id)
return formatted
# ✅ Хорошо: разбито на подфункции
def process_user(user_id):
user = get_user_or_none(user_id)
if not user:
return None
metrics = calculate_user_metrics(user)
formatted = format_metrics(metrics)
save_to_cache(user_id, formatted)
send_notification(user_id)
return formattedКогда комментарии нужны:
# ✅ Хорошо: объясняет почему
# Используем линейный поиск, так как список маленький (< 10 элементов)
# и сортировка будет дороже
def find_user_by_id(users, target_id):
for user in users:
if user.id == target_id:
return user
return None
# ❌ Плохо: пересказывает код
# Проверяем, что пользователь не None
if user is not None:
process(user)Когда комментарии НЕ нужны:
| Правило | Пример |
|---|---|
| Отступы: 4 пробела | def func():␣␣␣␣pass |
| Макс. длина строки: 79-100 символов | if very_long_condition and another_condition: |
| Пустые строки между функциями | 2 пустые строки |
| Пустые строки между методами класса | 1 пустая строка |
| Импорты в начале файла | import os перед кодом |
# ✅ Правильный порядок импортов
# 1. Стандартная библиотека
import os
import sys
from typing import List, Optional
# 2. Сторонние библиотеки
import requests
from flask import Flask
# 3. Локальные импорты
from .models import User
from .services import UserService
# ❌ Неправильно: импорты перемешаны
from .models import User
import os
from flask import Flask__all__ или соглашения)_prefixed# ❌ Плохо: скрытая зависимость
CONFIG = load_config() # глобальная переменная
def process_data(data):
return transform(data, CONFIG)
# ✅ Хорошо: явная зависимость
def process_data(data, config):
return transform(data, config)except: или except Exception: без причины# ❌ Плохо: скрывает ошибки
try:
process(data)
except:
pass # Тихо игнорируем всё!
# ❌ Плохо: слишком широкое исключение
try:
result = api_call()
except Exception:
return None # Ловим даже KeyboardInterrupt!
# ✅ Хорошо: конкретная обработка
try:
result = api_call()
except requests.Timeout:
logger.warning("API timeout, retrying...")
return retry_api_call()
except requests.HTTPError as e:
logger.error(f"API error: {e.status_code}")
raise.format() и %map()/filter()is None вместо == Noneif not value для проверки на пустотуconst и let вместо var.then()?. для безопасного доступаНе проверяйте вручную то, что можно автоматизировать:
| Инструмент | Что проверяет |
|---|---|
| Black, autopep8 | Форматирование кода |
| flake8, pylint | Стиль, ошибки |
| mypy, pyright | Типы |
| isort | Сортировка импортов |
| pre-commit | Запуск перед коммитом |
# .pre-commit-config.yaml
repos:
- repo: https://github.com/psf/black
rev: 24.0.0
hooks:
- id: black
- repo: https://github.com/pycqa/flake8
rev: 7.0.0
hooks:
- id: flake8
- repo: https://github.com/pre-commit/mirrors-mypy
rev: v1.8.0
hooks:
- id: mypyРаспечатайте или сохраните этот чек-лист:
□ ИМЕНА: понятные, раскрывают намерение
□ ФУНКЦИИ: делают одну вещь, ≤ 30 строк
□ КОММЕНТАРИИ: объясняют «почему», а не «что»
□ СТИЛЬ: соответствует гайдлайну (PEP 8)
□ ОШИБКИ: обрабатываются конкретно, логируются
□ ЗАВИСИМОСТИ: явные, нет циклических импортов
□ ТЕСТЫ: покрывают новую логику
□ ТИПЫ: аннотации добавлены
□ ДОКУМЕНТАЦИЯ: docstrings, README обновлены
Ключевая мысль: Чек-листы — это инструмент, а не догма. Адаптируйте их под свою команду и проект. Автоматизируйте всё, что можно автоматизировать.
Вопросы ещё не добавлены
Вопросы для этой подтемы ещё не добавлены.