<img src="../banner.png" width="100%" alt="bugfix-protocol banner">

Русский — Официальная русская версия bugfix-protocol.

Bugfix Protocol: Систематическая 6-фазная отладка

Структурированный подход к ошибкам — от анализа симптомов до проверки. Предотвращает бесцельный метод проб и ошибок и гарантирует устойчивость исправлений.

---

Обзор и цель

Фаза	Название	Цель	Макс. время
1	Быстрые проверки	Исключить очевидные причины	2 мин
2	Диагностика	Локализовать первопричину	10 мин
3	Изолированный тест	Сделать баг воспроизводимым	5 мин
4	Исправление	Минимальная коррекция	10 мин
5	Верификация	Проверить исправление + проверить побочные эффекты	5 мин
6	Документирование	Сохранить знания	2 мин

Правило 20 минут: Если через 20 минут прогресс отсутствует, измените подход или обратитесь за помощью.

---

Фаза 1: Быстрые проверки (2 мин)

Прежде чем погружаться глубоко — проверьте наиболее частые причины:

Чек-лист

• Синтаксическая ошибка? Внимательно прочитайте сообщение об ошибке, проверьте строку
• Ошибка импорта? Модуль установлен? Имя правильное? Циклический импорт?
• Опечатка? Правильно ли указаны имена переменных/функций?
• Неверный тип данных? String вместо int? None там, где ожидался объект?
• Устаревший кэш? Удалите __pycache__, перезапустите
• Неверное окружение? Активно ли правильное venv? Правильная ли версия Python?
• Кодировка? UTF-8 против cp1252 (классический Windows)

Быстрые действия

# Очистить кэш
find . -name "__pycache__" -type d -exec rm -rf {} + 2>&1
find . -name "*.pyc" -delete 2>&1

# Проверить импорты
python -c "import modulename"

# Проверить синтаксис
python -m py_compile file.py

---

Фаза 2: Диагностика (10 мин)

Стратегия: Снаружи внутрь (Outside-In)

1. Анализ сообщения об ошибке — Читайте трассировку стека (traceback) снизу вверх
2. Проверка последних изменений — git diff, git log --oneline -10
3. Использование диагностических утилит — Используйте специфичные для проекта инструменты

Диагностические утилиты (Примеры)

В зависимости от проекта могут пригодиться специализированные скрипты диагностики:

Инструмент	Назначение
import_diagnose.py	Анализ проблем с импортом
method_analyzer.py	Проверка сигнатур методов
env_checker.py	Валидация переменных окружения/путей

Примечание: Создавайте специфичные для проекта диагностические утилиты или используйте существующие. Важен систематический подход, а не конкретный инструмент.

Методы отладки

# 1. Отладка через print (быстро, но эффективно)
print(f"DEBUG: variable={variable!r}, type={type(variable)}")

# 2. Точка останова (интерактивно)
breakpoint()  # Python 3.7+

# 3. Расширенный traceback
import traceback
traceback.print_exc()

# 4. Логирование вместо print
import logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)
logger.debug(f"State: {state!r}")

---

Фаза 3: Изолированный тест (5 мин)

Минимальный воспроизводимый пример (MRE)

Цель: Воспроизвести баг с минимальным количеством кода.

# test_bug.py — Минимальный тест воспроизведения
"""
Bug: [Краткое описание]
Expected: [Что должно произойти]
Actual: [Что происходит вместо этого]
"""

# Минимальная настройка
# ... только самое необходимое

# Триггер бага
# ... точный код, вызывающий баг

# Ожидаемый результат
# assert result == expected, f"Got {result}"

Стратегии изоляции

1. Новый файл: Воспроизведите баг в отдельном файле
2. Удаление зависимостей: По одной, пока баг не исчезнет
3. Бинарный поиск: Разделите блок кода пополам, проверьте, в какой половине баг
4. Git bisect: git bisect start, git bisect bad, git bisect good <commit>

---

Фаза 4: Исправление (10 мин)

Принципы

1. Минимальность: Меняйте как можно меньше
2. Понимание: Никогда не чините вслепую — поймите, ПОЧЕМУ код сломан
3. Одна задача: Одно исправление на коммит, не чините несколько проблем одновременно
4. Обратная совместимость: Не ломайте существующий функционал

Шаблоны исправлений

# ПЛОХО: Лечение симптома
try:
    result = broken_function()
except:  # Подавление всех исключений
    result = default_value

# ХОРОШО: Исправление первопричины
def broken_function():
    if input_data is None:  # Настоящая причина: отсутствие проверки на None
        return default_value
    return process(input_data)

Распространенные категории исправлений

Категория	Типичное исправление
None/Null	Защитное условие: if x is None: return default
Ошибка индекса	Проверка границ: if i < len(lst)
Ошибка типа	Явное приведение: str(x), int(x)
Ошибка импорта	Исправить путь, установить пакет
Кодировка	Явно указать UTF-8: encoding='utf-8'
Состояние гонки	Блокировка/Мьютекс или изменение порядка
Баг состояния	Проверить инициализацию, добавить сброс

---

Фаза 5: Верификация (5 мин)

Чек-лист

• Баг исправлен: Исходная проблема больше не возникает
• MRE проходит: Изолированный тест выполняется успешно
• Нет регрессий: Существующие тесты по-прежнему проходят
• Граничные случаи: Проверены пустой ввод, None, большие объемы данных
• Утилиты проекта: Проверьте директорию утилит проекта на наличие тестов/валидаторов

Команды тестирования

# Юнит-тесты
python -m pytest tests/ -v

# Только затронутые тесты
python -m pytest tests/test_module.py -v -k "test_name"

# Проверка типов
python -m mypy file.py

# Линтер
python -m flake8 file.py

---

Фаза 6: Документирование (2 мин)

Шаблон отчета об ошибке

## Bug Report: [Краткий заголовок]

**Date:** YYYY-MM-DD
**Severity:** critical / high / medium / low
**Component:** [Модуль/Файл]

### Symptom
[Что видит пользователь / сообщение об ошибке]

### Root Cause
[Техническая первопричина]

### Fix
[Что было изменено + почему]

### Affected Files
- `file1.py` — [Изменение]
- `file2.py` — [Изменение]

### Prevention
[Как предотвратить подобный баг в будущем?]

Формат сообщения коммита

fix: [Краткое описание исправления]

Cause: [Первопричина в одном предложении]
Fix: [Что было изменено]
Test: [Как проверялось]

---

PyQt6 / Отладка GUI — Распространенные ловушки

Этот раздел актуален для десктопных GUI-проектов на PyQt6/PySide6.

Топ-5 ловушек PyQt6

Ловушка	Проблема	Решение
Отключение Signal-Slot	Сигнал подключен, но обработчик не выполняется	print в обработчике, проверка сигнатуры
Потокобезопасность	Обновление GUI из рабочего потока	QMetaObject.invokeMethod или использование сигнала
Каскад макета (Layout)	Виджет не виден / смещен	widget.show(), проверка иерархии layout
Блокировка цикла событий	Зависание GUI	Перенести долгие операции в QThread
Сборка мусора	Виджет внезапно исчезает	Сохранять ссылку как self.widget

Вспомогательные функции отладки PyQt6

# Дамп иерархии виджетов
def dump_widget_tree(widget, indent=0):
    print(" " * indent + f"{widget.__class__.__name__}: {widget.objectName()}")
    for child in widget.findChildren(QWidget):
        if child.parent() == widget:
            dump_widget_tree(child, indent + 2)

# Отладка сигналов
from PyQt6.QtCore import QObject
original_connect = QObject.connect
def debug_connect(self, *args, **kwargs):
    print(f"CONNECT: {self.__class__.__name__} -> {args}")
    return original_connect(self, *args, **kwargs)

---

Быстрая справка

ОШИБКА НАЙДЕНА?
     |
     v
[Фаза 1: Быстрые проверки]  ───── Очевидно? -> ИСПРАВИТЬ
     |
     v
[Фаза 2: Диагностика]  ────────── Причина ясна? -> Фаза 4
     |
     v
[Фаза 3: Изолированный тест]  ── Воспроизводимо? -> Фаза 4
     |                                |
     |                           Не воспроизводится?
     |                                |
     |                           Добавить логирование,
     |                           ждать повторения
     v
[Фаза 4: Исправление]  ────────── Минимальное + понятное
     |
     v
[Фаза 5: Верификация]  ───────── Тесты пройдены? -> Фаза 6
     |                                |
     |                           Тесты провалены? -> Назад к Фазе 4
     v
[Фаза 6: Документирование]  ──── Отчет об ошибке + коммит

Правило 20 минут

Если вы застряли через 20 минут:

1. Измените подход — Попробуйте другой метод отладки
2. Метод утенка — Объясните проблему вслух (или запишите ее)
3. Сделайте перерыв — Отодите на 5 минут, вернитесь со свежим взглядом
4. Обратитесь за помощью — Спросите коллегу, проверьте Stack Overflow или документацию
5. Сброс — git stash, начните с чистого листа