Резюме
Тесты — это одна из тех вещей, написание которых может показаться пустой тратой времени, но в конечном итоге окупается в виде выигранного времени за счет предотвращения попадания ошибок в производство. Чем раньше вы получите тестовое покрытие типа, тем лучше.
В этой главе мы узнали, как использовать модуль Spec для написания модульных тестов и компонент Athena::Spec для написания интеграционных тестов. Поскольку это два наиболее распространенных типа тестов, понимание того, как писать хорошие тесты, а также изучение преимуществ того, почему написание тестов является такой хорошей идеей, может оказаться невероятно полезным для обеспечения общей надежности приложения.
В следующей главе мы рассмотрим еще одну вещь, которая не менее важна, чем тесты, — как документировать ваш код/проект.
15. Документирование кода
Независимо от того, насколько хорошо реализован shard, если пользователь не знает, как его использовать, он не сможет использовать его в полной мере или полностью откажется. Хорошо документированный код может быть так же важен, как и хорошо написанный или хорошо протестированный код. Как предлагает https://documentation.divio.com, правильная документация для программного продукта должна охватывать четыре отдельные области:
• Учебники
• Практические руководства
• Пояснения
• Использованная литература
Каждая из этих областей позволяет вам использовать документацию в зависимости от того, что вы хотите сделать — например, хотите решить конкретную проблему или выяснить параметры конкретного метода. Хотя первые три лучше всего реализуются с помощью кода, Crystal поставляется с некоторыми простыми в использовании функциями документирования кода, которые могут сделать создание справочной документации довольно безболезненным.
В этой главе мы рассмотрим следующие темы:
• Документирование кода Crystal.
• Директивы документации
• Создание документации.
После прочтения этой главы вы должны иметь представление об инструментах и функциях, которые можно использовать для документирования вашего кода. В конечном итоге это позволит пользователям шарда быстро приступить к работе и легко научиться его использовать.
Технические требования
Для этой главы вам понадобится работающая установка Crystal.
Инструкции по настройке Crystal см. в Главе 1 «Введение в Crystal».
Все примеры кода для этой главы можно найти в папке Chapter 15 репозитория GitHub этой книги: https://github.com/PacktPublishing/Crystal-Programming/tree/main/Chapter15.
Документирование кода Crystal
Комментарии к коду, добавляемые к типам, методам, макросам и константам, считаются комментариями к документации. Компилятор позволяет нам извлечь документацию для создания веб-сайта HTML и ее представления. Мы вернемся к этому позже в этой главе.
Чтобы комментарий действовал как документация, его необходимо разместить непосредственно над элементом, без пустых строк. Пустые строки допускаются, но перед ними также должен стоять символ #, чтобы цепочка комментариев не прерывалась. Давайте посмотрим на простой пример:
# This comment is not associated with MyClass.
# A summary of what MyClass does.
class MyClass; end
В этом примере есть два комментария: один связан с MyClass, а другой — нет. Первый абзац следует использовать в качестве резюме, определяющего назначение и функциональность элемента. Первый абзац включает в себя весь текст, вплоть до точки или пустой строки комментария, как показано здесь:
# This is the summary
# this is still the summary
#
# This is not the summary.
def foo; end
# This is the summary.
# This is no longer the summary.
def bar; end
Здесь метод #foo имеет многострочное резюме, которое заканчивается пустой новой строкой. С другой стороны, метод #bar использует точку для обозначения конца сводки и начала тела. Crystal генерирует документацию HTML и JSON на основе комментариев к документу. Подробнее о том, как на самом деле генерировать документацию, читайте далее в этой главе, а пока давайте просто посмотрим, как она будет выглядеть: