Инструмент оценки качества кода

📝 Описание

Автоматизированный инструмент для оценки качества Python-кода в образовательных целях. Оценивает код студентов по множеству метрик, включая соответствие PEP 8, цикломатическую сложность, качество документации и дублирование кода. Генерирует детальные отчёты с практическими рекомендациями по улучшению.

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

✨ Возможности

• 🔍 Многометрический анализ

  • Проверка соответствия PEP 8 (через flake8)
  • Анализ цикломатической сложности (через radon)
  • Оценка покрытия документацией (наличие docstring)
  • Валидация длины функций
  • Обнаружение дублирования кода

• 📊 Гибкая система отчётов

  • Текстовые отчёты для терминала
  • JSON отчёты для программной обработки
  • Красивые HTML отчёты с цветовой индикацией

• 🌍 Мультиязычная поддержка

  • Английский (en-US)
  • Русский (ru-RU)
  • Легко добавить другие языки

• 🎯 Образовательный фокус

  • Практические рекомендации для студентов
  • Понятная шкала оценок (A-F)
  • Подробные объяснения проблем

• ⚡ Быстро и современно

  • Использует менеджер пакетов
    uv
  • Автоматизированный CI/CD через GitHub Actions
  • Запланированный мониторинг качества

• 🔧 GitHub Action

  • Используйте как переиспользуемый action в ваших workflows
  • Автоматическая проверка качества кода при PR/push
  • Настраиваемые пороговые значения и отчёты

🚀 Установка

Вариант 1: Использование как GitHub Action (Рекомендуется)

Добавьте в ваш workflow (

См. ACTION_USAGE.md для полной документации.

Вариант 2: Локальная установка

Требования

• Python 3.11 или выше
• Менеджер пакетов
  uv

Настройка

1. Установите uv (если ещё не установлен):

2. Клонируйте репозиторий:

3. Установите зависимости:

Готово! Инструмент готов к использованию.

📖 Использование

Анализ одного файла

Вывод:

============================================================
Отчёт о качестве кода для example_bad.py
============================================================
Общая оценка: 58/100 D (Неудовлетворительно)

Детальные метрики:
------------------------------------------------------------
Соответствие PEP8:        45/100 (23 нарушения)
Сложность:               70/100 (средн: 8.4)
Документация:            40/100 (4/10 документировано)
Длина функций:          60/100 (2 длинные функции)
Дублирование кода:       80/100

Рекомендации:
------------------------------------------------------------
• Исправить 23 нарушения PEP8 для улучшения стиля кода
  - Уменьшить длину строк (макс 88 символов)
  - Исправить проблемы с пустыми строками
• Добавить docstrings к 6 функциям/классам
  - Функция: calculate_grade
  - Функция: process_data
  - Класс: DataProcessor
• Разбить длинные функции на более мелкие
  - very_long_function_that_does_too_many_things (45 строк)
============================================================

Анализ директории

Это проанализирует все Python файлы в директории

Генерация JSON отчёта

Отлично подходит для интеграции с системами оценивания или конвейерами анализа данных.

Параметры командной строки

Мультиязычные отчёты

Генерируйте отчёты на разных языках:

Пример вывода на русском:

============================================================
Отчёт о качестве кода для example_good.py
============================================================
Общая оценка: 98/100 A (Отлично)

Детальные метрики:
------------------------------------------------------------
Соответствие PEP8:        100/100 (0 нарушений)
Сложность:             100/100 (средн: 0.0)
Документация:          100/100 (7/7 документировано)
Длина функций:        100/100 (0 длинных функций)
Дублирование кода:        80/100

Рекомендации:
------------------------------------------------------------
• Рефакторинг дублированного кода в переиспользуемые функции
============================================================

Генерация HTML отчёта на русском

🧪 Запуск тестов

📁 Структура проекта

code-quality-checker/
├── .github/
│   └── workflows/
│       ├── tests.yml              # CI/CD для тестирования
│       └── scheduled-analysis.yml # Еженедельные отчёты качества
├── src/
│   └── code_quality/
│       ├── __init__.py           # Инициализация пакета
│       ├── analyzer.py           # Основной движок анализа
│       ├── metrics.py            # Калькуляторы метрик
│       ├── report.py             # Генерация отчётов
│       ├── cli.py                # Интерфейс командной строки
│       ├── i18n.py               # Интернационализация
│       └── locales/
│           ├── en-US.json        # Английские переводы
│           └── ru-RU.json        # Русские переводы
├── tests/
│   ├── __init__.py
│   ├── test_analyzer.py          # Тесты анализатора
│   ├── test_metrics.py           # Тесты метрик
│   ├── test_i18n.py              # Тесты i18n
│   └── fixtures/
│       └── sample_code.py        # Тестовые фикстуры
├── examples/
│   ├── example_bad.py            # Пример низкого качества
│   └── example_good.py           # Пример высокого качества
├── .gitignore
├── pyproject.toml                # Конфигурация uv
└── README.md

🤖 Возможности CI/CD

Автоматизированное тестирование

Каждый push и pull request запускает:

• ✅ Проверки линтинга через Flake8
• ✅ Полный набор тестов с отчётом о покрытии
• ✅ Проверка форматирования через Black
• ✅ Сводка покрытия в комментариях к PR

Запланированный анализ качества

• 🕐 Еженедельные отчёты: Автоматический запуск каждое воскресенье
• 📦 Загрузка артефактов: Хранение отчётов в течение 90 дней
• 📝 Автоматические коммиты: Сохранение исторических данных о качестве
• 🚨 Оповещения о качестве: Создание issues при падении оценки ниже 70
• 🎮 Ручной запуск: Запуск анализа по требованию с пользовательскими параметрами

Запустить вручную:

Перейти в Actions → Weekly Code Quality Report → Run workflow

📊 Объяснение метрик

Соответствие PEP 8 (вес 25%)

Проверка соответствия руководству по стилю Python через flake8. Типичные проблемы:

• Длина строки превышает 88 символов
• Неправильные пробелы и отступы
• Проблемы с порядком импортов

Оценка: 100 - (нарушения × 5), минимум 0

Цикломатическая сложность (вес 25%)

Измеряет сложность кода через radon. Чем меньше, тем лучше:

• 1-5: Отлично (100 баллов)
• 6-10: Хорошо (80 баллов)
• 11-20: Удовлетворительно (60 баллов)
• >20: Требует рефакторинга (<40 баллов)

Документация (вес 25%)

Проверка наличия docstrings в функциях и классах:

• Оценка = (документировано / всего) × 100
• Отсутствующие docstrings вызывают конкретные рекомендации

Длина функций (вес 15%)

Функции должны быть краткими и сфокусированными:

• Идеально: < 50 строк на функцию
• Штраф: -20 баллов за каждую длинную функцию

Дублирование кода (вес 10%)

Обнаружение повторяющихся последовательностей кода:

• Использует сопоставление последовательностей из 3 строк
• Штраф: -10 баллов за каждый дубликат

📋 Требования

Зависимости управляются через

• Основные:

  • flake8 >= 7.0.0
  • radon >= 6.0.0
  • black >= 24.0.0

• Разработка:

  • pytest >= 8.0.0
  • pytest-cov >= 4.1.0

🎓 Варианты использования

Для преподавателей

Для студентов

Для команд

Включите GitHub Actions для автоматической проверки качества кода при каждом pull request.

🛠️ Разработка

Добавление новых метрик

1. Добавьте калькулятор метрики в
   src/code_quality/metrics.py
2. Интегрируйте в анализатор в
   src/code_quality/analyzer.py
3. Обновите генератор отчётов в
   src/code_quality/report.py
4. Добавьте тесты в
   tests/test_metrics.py

Локальная разработка

📈 Примеры оценок

🤝 Участие в разработке

Приветствуются вклады! Пожалуйста, не стесняйтесь отправлять Pull Request.

1. Форкните репозиторий
2. Создайте ветку для вашей функции (
   git checkout -b feature/AmazingFeature
   )
3. Закоммитьте изменения (
   git commit -m 'Add some AmazingFeature'
   )
4. Запушьте в ветку (
   git push origin feature/AmazingFeature
   )
5. Откройте Pull Request

📄 Лицензия

Этот проект лицензирован под лицензией MIT - см. файл LICENSE для деталей.

🙏 Благодарности

• Создан с помощью uv для быстрого управления пакетами
• Использует flake8 для проверки PEP 8
• Использует radon для анализа сложности
• Отформатирован с помощью black

📞 Поддержка

Если у вас возникли проблемы или вопросы:

• Откройте issue на GitHub
• Проверьте существующие issues для решений
• Ознакомьтесь с документацией

Сделано с ❤️ для преподавателей и студентов