Процессы, сроки, темы

Общая информация и порядок работы

Командный проект предлагается на команду из 2-3 человек. Основное требование к проекту: это должен быть законченный программный продукт. Проект при сдаче будет оцениваться по следующим критериям:

1. Соответствие реализованной функциональности требуемой в проекте.

2. Поэтапность разработки через системы контроля версий.

3. Покрытие тестами, включая unit тестирование.

4. Стиль программирования (Code Style).

5. Практика использования CI.

6. Полнота документации.

7. Итоговая презентация.

Команда может предложить свою тему в дополнение к перечисленным ниже.

С 8 по 21 февраля — выбор и согласование темы.

С 22 февраля по 7 марта – разработка первой версии ТЗ.

С 8 по 19 марта — разработка и согласование ТЗ и плана работ.

С 20 марта — начало кодирования.

С 22 апреля — отладка, документация, интеграционное тестирование, готовность показать beta-версию программы.

С 1 мая – быть готовыми представлять законченный проект.

К защите допускаются команды, не имеющие долгов по лабораторным занятиям, а также предоставившим beta-версию программы в срок.

Выбор темы и формирование команды

1. В установленный срок выберите тему и согласуйте ее с преподавателем практики. В одной группе темы не могут повторяться.

2. Для создания команды и репозитория пройдите по ссылке: GitHub Classroom: trpo2023/cw

3. Если команда еще не создана, создайте ее. Укажите название команды по шаблону: <группа>_<тема>. Например: iv-221_search-engine. Если в команде участвуют студенты из разных групп, то укажите все: ip-211_ip-212_fuzzy-matching. Hint: договоритесь между собой, кто из участников создает команду.

   Если команда создана, найдите ее в списке и нажмите Join.

4. В репозитории создайте файл docs/tech-requirement.md с техническим заданием. В файле README.md отметьте название темы курсовой работы. В разделе issues заведите задачи на разработку.

5. По готовности ТЗ и плана работ заполните форму: ТРПО 2023: ТЗ и план работ.

Содержание ТЗ

Техническое задание (ТЗ) — документ, содержащий набор требований к проекту. По итогу составления ТЗ у заказчика и исполнителя должно сформироваться общее видение проекта. Приемочное тестирование продукта будет выполняться с учетом заявленной в ТЗ функциональности.

В зависимости от специфики компании и проекта ТЗ может принимать различную форму. По мере развития проекта ТЗ может уточняться в силу изменчивости требований.

На первой итерации ТЗ должно включать как минимум следующие пункты.

1. Функциональность проекта. Описание с точки зрения пользователя: какие задачи решает продукт, какие покрывает сценарии использования.

2. Формат входных данных.

3. Интерфейс приложения. В каком режиме работает приложение (интерактивный или нет, фоновый процесс, сетевой сервис и т. д.). Какие элементы интерфейса предусмотрены, их поведение.

4. Если приложение принимает аргументы командной строки, то их формат и описание.

5. Если предполагается использовать чтение исходных данных извне программы: конфигурационного файла, базы данных, источников в Интернет и т.д., то необходимо описание формата / протокола взаимодействия.

Составление плана работ

После составления ТЗ необходимо декомпозировать проект на ряд задач. Каждая задача должна быть достаточно конкретизирована, чтобы участники команды понимали ее содержание, DoD (definition of done) и могли оценить сроки ее выполнения. Необходимо также предоставить план тестирования созданного продукта.

Задачи следует создавать в разделе issues проекта.

Составленный план работ не является окончательным и может быть скорректирован в процессе разработки, но является обязательным начальным этапом и должен быть максимально полным исходя из ТЗ.

Защита проекта

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

1. ТЗ проекта и итоговый план работ на команду.

2. Описание командной работы и полученного результата.

3. Описание личного вклада в результат работы команды.

Для законченных проектов будет организован процесс защиты перед заказчиками, успешное прохождение которого может существенно облегчить процесс итоговой аттестации в виде экзамена. Для защиты проекта нужно будет предоставить в наглядном виде:

1. ТЗ и итоговый план работ.

2. Сделанный продукт, для детализации см. критерии оценки в начале.

3. Распечатанный отчет.

Для защиты команда готовит презентацию. Регламент защиты:

1. Тимлид начинает презентацию проекта. Озвучиваются технические требования к проекту (ТЗ), декомпозицию задачи (план работ) и распределение ролей в команде.

2. Далее каждый участник команды рассказывает о своей части работы. В процессе необходимо продемонстрировать рабочую функциональность и фрагменты кода.

На доклад отводится 5−7 минут.

Оформление отчета

Шаблон: trpo_report_template.odt.

Документ подготовлен в LibreOffice Writer и может некорректно отображаться в Microsoft Word.

Оценка за курсовой проект может быть выставлена только при наличии отчета. У каждого участника команды должен быть свой личный отчет.

Для оформления следует использовать настроенные стили:

1. Heading 1 и Heading 2 для заголовков и подзаголовков.

2. Text body для основного текста.

3. Table Heading и Table Contents для заголовков таблиц и содержимого ячеек.

4. Code для исходного кода.

Процесс работы над проектом

Текст носит рекомендательный характер. На практике организация процесса разработки может отличаться. Если вы придерживаетесь других соглашений, их следует задокументировать на отдельной странице в wiki проекта, выбор должен быть аргументирован.

ТЗ и план работ

До начала реализации проекта необходимо подготовить техническое задание и план работ.

ТЗ позволяет сформировать общее видение проекта у разработчиков и заказчиков. Документ должен быть размещен в wiki 1 проекта. Распространение ТЗ в виде файлов может привести к расхождению версий документа у всех участников.

Задачи создаются в разделе issues 2. Список задач помогает оценивать фронт работ, отслеживать статус задач, выбирать задачи к реализации. Задача состоит из заголовка и описания. Заголовок должен быть коротким и ясным, отражать суть задачи и отвечать на вопрос «Что нужно сделать?». В описании задачи следует размещать дополнительные детали: замечания о реализации, ссылки на фрагменты ТЗ, при необходимости допускается размещение ссылок на другие задачи (например, «Брать в работу после выполнения задачи #42»).

При необходимости указывать DoD задачи (Definition of Done, критерии готовности).

Пример исследовательской задачи:

Выбрать библиотеку для выполнения HTTP-запросов

Собрать список популярных библиотек, доступных для языков С и С++, с каждой из них реализовать простой пример получения веб-страницы.

DoD: в wiki написана статья со сравнением библиотек и примерами кода, проведено обсуждение с разработчиками, результат обсуждения записан в комментариях к задаче.

Также у задач есть поля: Assignee (исполнитель), Tags, Milestones.

Поле Assignee заполняет либо сам исполнитель, либо другой разработчик, если исполнитель известен заранее. Если поле Assignee пустое, значит, задача свободна и ее можно брать в работу. Игнорирование этого поля может привести к тому, что одну и ту же функциональность независимо реализуют несколько разработчиков.

Tags — дополнительные метки задачи. Могут быть использованы как фильтры для поиска или признаки для классификации задач. Использование остается на усмотрение команды. Пример использования можно посмотреть в репозитории bootstrap 3.

Milestones — вехи развития проекта. Задачи можно сгруппировать по майлстоунам. Например, можно завести майлстоуны Beta и Release, в каждый из которых включить некоторое подмножество задач и установить договоренность: в Beta попадает необходимый для защиты проекта минимум задач, а версия Release будет выпущена, если останется время.

1

About GitHub Wikis

2

Mastering issues

3

Bootstrap

Дополнение списка задач

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

1. Существующая задача оказывается слишком крупной и должна быть декомпозирована на несколько. В этом случае задача закрывается, создаются более мелкие.

2. При работе над проектом была обнаружена ошибка, исправление которой либо выходит за рамки текущей задачи, либо требует ощутимых затрат по времени, либо может быть исправлена позже, и т. д. В этом случае также создается новая задача.

Подготовка инфраструктуры

В рамках лабораторных работ вы двигались от простого к сложному, постепенно добавляя новые инструменты в рабочий процесс.

На практике перед началом разработки следует подготовить инфраструктуру:

1. Создать репозиторий.

2. Подготовить систему сборки (написать Makefile).

3. Настроить автоматические сборки в CI.

Написание Unit-тестов не является завершающим этапом разработки проекта. Тесты пишутся в процессе выполнения каждой задачи. Наличие тестов — негласный Definition of Done.

Рабочий процесс

Резюмируя вышесказанное, к моменту начала кодирования у вас должны быть:

1. ТЗ в wiki

2. Список задач в Issues

3. Репозиторий с каркасом проекта, где подготовлены система сборки, настроен CI и все готово для добавления модульных тестов.

Дальнейший процесс состоит из следующих шагов:

1. Выбрать задачу из issues, на которой нет исполнителя. Назначить ее на себя.

2. Создать в репозитории ветку для реализации задачи. Желательно договориться об именовании веток. Например, ветки можно называть по номерам задач: issue-1, issue-2, issue-42. Допускается дополнять названия веток краткими метками: issue-42-user-score.

3. Реализовать задачу. При оформлении коммитов руководствоваться соглашениями 4.

4. Написать тесты, покрывающие разработанную функциональность.

5. Если ветка master ушла вперед, то выполнить rebase своей ветки на master 5. Убедиться, что после ребейза сборка успешно проходит в CI.

6. Смержить ветку в мастер с ключом --no-ff.

7. Закрыть задачу. При необходимости оставить комментарии с пояснениями о выполнении.

Порядок может меняться. Например, если задача требует исправления ошибки, то сначала пишется тест для воспроизведения проблемы (тест должен падать), а затем реализуется исправление ошибки.

4

How to Write a Git Commit Message

5

A simple git branching model

Распространенные ошибки

ТЗ в последний момент

Как правило, ТЗ требует согласования и редко остается в своем первоначальном виде. Подготовка в последний момент не позволяет предотвратить наиболее фатальные ошибки.

Делегирование разработки юнит-тестов

Наличие юнит-тестов — часть DoD задачи. Без тестов задача не считается выполненной. Тесты пишет тот же разработчик, что и реализовывал функциональность. На практике это не всегда так, но осознанно полностью делегировать юнит-тесты для покрытия роли тестировщика в команде не следует.

Подгон под ответ

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

Избыточная детализация задач

Если в формулировка задачи расписана с точностью до используемых переменных и последовательности вызова функций, то, скорее всего, эта задача уже была решена, а заведение ее в список — фикция.

Подмена основных активностей побочными

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

Некоторые признаки некачественного кода

В процессе проверки курсовых проектов помимо названных выше критериев мы обращаем внимание на качество кода. Ниже приведены некоторые наиболее распространенные ошибки. Рекомендуется в конце выполнения каждой задачи просматривать код на наличие следующих «запахов» (code smell).

1. Дублирование кода.

   Повторяющийся код — один из признаков нарушения принципа DRY (Don’t repeat yourself).

   См. Duplicate Code, Comments.

2. Длинная функция.

   Функция должна решать одну задачу. Такие функции проще читать, поддерживать и тестировать. Длинная функция может быть признаком нарушения принципов DRY, SRP (Single Responsibility Principle) и/или SLA (Single Level of Abstraction)

   См. Long Method

3. Длинный список параметров.

   Пример:

   bool triangle_intersects_triangle(
       double t1x1, double t1y1,
       double t1x2, double t1y2,
       double t1x3, double t1y3,
       double t2x1, double t2y1,
       double t2x2, double t2y2,
       double t2x3, double t2y3
   );
   

   Должно быть:

   bool triangle_intersects_tirangle(Triangle lhs, Triangle rhs);
   

   См. Long Parameter List.

4. Магические константы.

   См. Magic Number

5. User-specific code.

   Пример:

   FILE* f = fopen("/home/v.pupkin/myproject.dict.txt", "r");
   

   Если в коде используется абсолютный путь, содержащий имя пользователя, то этот код не может быть переносимым. Такие константы следует выносить в конфиг или параметры командной строки.

6. Использование глобальных переменных.

   См. Global Variables Are Bad.

Выбор инструментов

Лабораторные работы выполняются на языке C. Для разработки курсового проекта вы можете выбрать язык на свое усмотрение, но необходимо, чтобы все участники команды были знакомы с выбранным языком на достаточном уровне.

Запрещается использовать слишком высокоуровные инструменты: Unity, Unreal Engine и др. Мы ожидаем, что большая часть вашей работы будет заключаться в ручном написании кода и работе с инструментами, а не в сборке конструктора из готовых блоков. Кроме того, у вас могут возникнуть сложности с настройкой CI, и работа не будет выполнена в полном объеме.

Запрещается использовать устаревшие инструменты. Например, библиотеку BGI, известную некоторым из вас по заголовочному файлу graphics.h. Последняя среда разработки с поддержкой этой библиотеки была выпущена в 1997 году, более двадцати лет назад.

Поиск актуальных полезных библиотек можно начать отсюда: getAwersomeness()

Темы

Для каждой темы указан рекомендованный размер команды. Если вы планируете собрать команду больше рекомендуемой, то следует более детально продумать план работ. Часто возникает ситуация, когда в небольшом проекте сложно найти задачи для всей команды.

Некоторые проекты являются упрощенными клонами существующих систем. Для составления ТЗ рекомендуется ознакомиться с указанными и другими существующими реализациями.

2 человека:

1. Hangman. Виселица.

2. Игра «Жизнь»

3. Пятнашки.

4. Игра «100 спичек»

5. Игра «Ним» (три кучки спичек)

6. Сортировка входных данных (аналог sort)

7. Программа символы: проверка сбалансированности скобок в программе на С

8. Интерпретатор языка программирования Машины Тьюринга

9. Система сборки (аналог make)

10. Вывод фрагментов файлов (аналог head и tail, с обязательной реализацией режима --follow).

2−3 человека:

11. QuizRunner. Система проведения тестирования.

12. KeyboardNinja. Клавиатурный тренажер.

13. FileProcessor. Приложение для массового переименования файлов в указанном каталоге по заданным шаблонам.

14. Formatter. Приложение для форматирования текста: выравнивание, разбивка на абзацы, разбивка на страницы с колонтитулами и т. д.

15. Приложение для рекомендации оптимального тарифа на основе затрат

16. Задачи на графах: кратчайший путь между городами, количество разных маршрутов между городами, длиннейший путь между городами

17. Движок SQL-запросов к данным в формате CSV

18. Генератор документации по комментариям в исходном коде (аналог doxygen)

19. Конвертер файлов из Markdown в HTML (аналог pandoc)

20. Todo лист

21. Анализ использования диска (аналог ncdu)

22. Unit Converter (аналог units)

23. Password Generator (аналог pwgen)

24. Генератор статичных сайтов (аналог jekyll)