тестирование документации
.docxМинистерство образования и науки РФ
Федеральное государственное автономное образовательное учреждение высшего образования
«Омский государственный технический университет»
Кафедра «Информатика и вычислительная техника»
Отчет по лабораторной работе №3
по дисциплине
«Документирование программного обеспечения»
Выполнил
Студент гр. ПИН-221
Шадчнев Г.А. _______________
Проверил
Старший преподаватель
Фатеева А.С. _______________
Омск, 2025
Тестирование и оценка качества программной документации
1. Постановка задачи
Провести тестирование и оценку качества сгенерированной HTML-документации (lab1_doc.html) для проекта Лабораторной работы №1 ("Построение системы кодирования/декодирования сигналов"). Оценка производится на основе общезначимых критериев хорошей документации.
2. Методология тестирования
Тестирование проводилось в соответствии с принципами, изложенными в стандарте IEEE 829-2008 (ISO/IEC/IEEE 29119), и с использованием ключевых критериев, обеспечивающих качество технической документации.
Таблица 1 –
Критерий оценки |
Описание |
Примененная методика |
Полнота |
Наличие документации для всех публичных объектов (функций, констант). |
Сверка оглавления документации с исходным кодом (lab1_documented.py). |
Актуальность |
Соответствие описания (Args, Returns) фактической реализации кода. |
Ручная инспекция. Проверка, что pdoc корректно отображает сигнатуры функций. |
Структурированность документации |
Четкая организация разделов и работоспособность ссылок. |
Проверка навигационной панели, кликабельности ссылок, работы переключателя "View Source". |
Доступность и Язык |
Понятность текста и отсутствие языковых дефектов. |
Инспекция текста docstrings на русском языке, проверка орфографии и терминологии. |
3. Результаты тестирования
Общее количество протестированных объектов (функций и констант): 21. Тестирование признано успешным.
Таблица 1 – Сильные стороны документации
Аспект |
Описание |
Полное покрытие API |
Документация описывает 100% публичных объектов модуля (main, 19 вспомогательных функций, 1 константа CODE_TABLE). |
Автоматическая актуальность |
Использование pdoc гарантирует, что сигнатуры функций (имена, параметры) полностью соответствуют исполняемому коду. |
Корректность терминологии |
Ключевые термины ЛР1 (k, r, n, синдром, расширенный бит четности) корректно расшифрованы в разделах Args и Returns. |
Удобство навигации |
Левая боковая панель обеспечивает быстрый переход (якорные ссылки) к любому разделу в один клик. |
Доступность исходного кода |
Возможность для каждой функции просмотреть исходный Python-код через переключатель "View Source", что повышает прозрачность. |
Таблица 2 – Слабые стороны документации
Аспект |
Обнаруженная проблема |
Неполнота Docstring |
Некоторые вспомогательные функции, не имеющие параметров (например, invert_bit), не содержат явного тега Args, хотя их назначение понятно из описания. (Не критично, но не соответствует строгому стандарту). |
Отсутствие метаинформации |
Отсутствует явное указание на версию модуля или дату последней модификации в шапке документа. |
Объем текста |
В силу большого количества функций, объем документации значителен, что может затруднять восприятие неинициализированным пользователем (требует дополнительного раздела "Краткий обзор"). |
4. Заключение
В ходе лабораторной работы №3 было проведено тестирование HTML-документации, сгенерированной инструментом pdoc для проекта ЛР №1.
Выводы:
Положительная оценка: Документация lab1_doc.html обладает высокой полнотой, актуальностью и структурированностью. Критические дефекты, делающие документацию непригодной к использованию, не обнаружены.
Функциональные тесты: Все интерактивные элементы (переключатель "View Source", навигационные ссылки) функционируют корректно.
Рекомендации: Для повышения качества документации до уровня, соответствующего строгим промышленным стандартам, рекомендуется добавить метаинформацию о версии и дате, а также обеспечить явное описание всех входных и выходных параметров для каждой функции, независимо от ее сложности.