Skip to content

Latest commit

 

History

History
103 lines (79 loc) · 11.9 KB

lab-2-library.md

File metadata and controls

103 lines (79 loc) · 11.9 KB
Raw

Лабораторная работа #2: Разработка библиотеки по TDD

Цели

  1. Освоить практику разработки Test-Driven Development.
  2. Приобрести навыки создания сброчных скриптов CMake.
  3. Познакомиться с примером стиля кодирования на языке С++ на примере Google C++ Style Guide.
  4. Углубить следующие навыки:
    • Написание unit-тестов при помощи инструмента Google Test.
    • Взаимодействие с системой непрерывной интеграции GitHub Actions.
    • Прохождение инспекции кода (code review) на GitHub.

Задачи

  1. Нужно будет выбрать тему из списка и открыть PR, вписав своё имя в таблицу.
  2. Cоздать модуль, реализующий данный функционал. Модуль должен будет иметь:
    • Качественный API, оформленный в виде заголовочного файла.
    • Набор unit-тестов, дающий 100% покрытие кода.
    • Реализацию на языке С++, с целью сборки его в виде статической библиотеки.
  3. Интегрировать свой код в основую ветвь разработки, пройдя тестирование и рецензию кода.

Типичные ошибки

  1. Работу следует осуществлять только в своей личной директории.
  2. Позаботьтесь о качестве вашего кода и API в особенности. Давайте понятные имена своим переменным, не используйте сокращений, отделяйте логически несвязанные блоки кода пустыми строками, и так далее.
  3. В этой лабораторной работе не нужно добавлять приложений, использующих ваш класс. Никаких сэмплов и функций main, только сборка с тестами. Тесты — это лучшая иллюстрация работы с вашим классом, это "исполняемая документация".
  4. Оформление тестов:
    • Во всех тестах должны быть явные секции Arrange, Act, Assert.
    • Как правило должна быть только одна конструкция Assert.
    • Тесты должны читаться как реальный код, должны проверяться осмысленные пользовательские сценарии, давайте переменным осмысленные и понятные имена.
  5. Не заливайте никаких лишних файлов:
    • Бинарные файлы (результат компиляции)
    • Проекты, сгенерированные CMake (Microsoft Visual Studio и другие)

Детальные инструкции

Предварительная настройка

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

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

    $ git remote -v # Убеждаемся, что репозиторий upstream объявлен и имеет правильный адрес $ git fetch upstream $ git checkout -b lab2-YOUR-NAME upstream/main

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

    $ ctest -VV -S devtools_test.cmake

Далее можно приступать к выполнению собственно лабораторной работы.

Выполнение лабораторной

  1. Создайте новую директорию для своего модуля. Его необходимо расположить в директории modules и дать ему имя, отражающее суть проекта.
  2. Далее создайте в своей директории структуру, аналогичную той, что показана в проекте-примере (complex-number). У вас должны появиться три директории: include, src и test.
    • Затем скопируйте файл CMakeLists.txt из модуля complex-number в корень своего проекта и модифицируйте его под себя, там где это будет необходимо.
    • Также вы должны положить в свою папку src еще один файл CMakeLists.txt, описывающий построение вашего модуля. Его можно создать по примеру файла complex-number/src/CMakeLists.txt.
    • В директории test тоже должен быть свой CMakeLists.txt, описывающий модуль с тестами. Не забудьте также положить файл с функцией main. Его можно позаимствовать из директории complex-number/test.
  3. Далее вы должны приступить к главной части -- реализации своего класса в стиле TDD, следуя алгоритму Red-Green-Refactor. Подобно тому, как это было показано на демонстрации, следует итеративно наращивать функционал вашего класса, идя от простых случаев к более сложным. Напомним основные моменты:
    • Двигаться нужно очень маленькими шагами, чтобы каждая итерация занимала не более 5-10 минут. Если выходит дольше, значит следовало взять какой-то более простой случай.
    • Мы всегда начинаем с теста (а сам тест -- с Assert), и никогда не пишем код без красного теста.
    • Общие рекомендации:
      • Постарайтесь избегать лишних зависимостей в своем заголовочном файле.
      • Также желательно предоставлять минималистичный публичный интерфейс (секция public), позволяющий решить задачу, а все остальное поместить в private секцию класса (или protected).
  4. Как и в рамках демонстрации, рекомендуем создать pull request в самом начале работы над кодом. Желательно сначала открыть его внутри своего форка или отметить как Draft, чтобы не включаться в процесс ревью до готовности модуля. 
    $ git remote update # или git fetch upstream
$ git push origin/main upstream/main
$ git push origin HEAD
# после этого через веб-интерфейс GitHub можно открыть pull request в origin/main
  5. Затем, "крутясь" в цикле TDD предлагается реализовать полный функционал вашего класса и стабилизировать его, полагаясь на тестирование своего форка на сервере GitHub Actions.
    • Как и всегда, первым делом стоит добиться "зеленого" билда от GitHub Actions. Убедитесь, что ваш модуль построился и тесты на него были запущены и успешно прошли.
    • Скорее всего будет масса замечаний от скрипта cpplint.py, проверяющего стиль кодирования. Замечания нужно исправить и сделать коммиты в ту же ветку (git push origin HEAD), pull request обновится автоматически.
  6. Когда вы закончите, нужно будет открыть pull request в центральный репозиторий. Там следует убедиться, что покрытие кода достигло 100%. Когда вы пошлете pull request, система Codecov сообщит покрытие для вашего модуля. По результатам покрытие должно быть 100%, если у вас получилось меньше, нужно вернуться и добавить тестов.
    • Во время написания тестов вам может показаться, что ваш класс неудобен и его можно улучшить. В таком случае нужно вернуться и переделать (Refactor стадия цикла TDD).
    • Когда вы добъетесь "зеленого" билда, необходимо получить одобрение от двух сокурсников в виде approve. После этого пригласите на проверку интеграционных менеджеров.

ВНИМАНИЕ, РЕЦЕНЗЕНТЫ: как бы прекрасно ни была сделана лабораторная, вы обязаны попросить какой-нибудь ее доработки. В лучшем случае это будут найденные вами баги, как минимум -- какие-то другие мелкие запросы, например переименование или изменение форматирования. Но вы обязаны оправить автора что-то доделать, чтобы он добавил коммитов и пулл-реквест прошел еще одно тестирование.

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