Содержание
Каждый раз, когда вы открываете кусок кода, постарайтесь найти место, где вы можете описать, как этот класс или эта функция может быть использована другими разработчиками.
Сосредоточьтесь на примерах использования или сценариях применения.
Начать можно с описания PR.
Добавьте в описание PR несколько примеров использования. Это будет легкий старт без какого-либо давления, и его можно будет редактировать по мере необходимости на основе отзывов ваших коллег.
Добавьте примеры использования YARD
Другой способ - использовать структуру YARD для написания непосредственно перед классом или методом:
# @example Как заставить этот пример работать # # t = http://MyObect.new(...) # t.run(email_param: "test") #
Попробуйте написать пример, который при копировании/вставке в irb или rails console будет работать.
Мне это нравится, потому что большинство IDE умеют показывать примеры YARD во время написания кода, и таким образом у вас будут примеры использования ваших классов во время набора текста.
Написание документации в формате markdown
Если вам не нравится писать документацию внутри файлов кода, разместите ее вне файлов кода.
Проще всего создать папку ./docs внутри вашего проекта и писать в ней файлы в формате markdown. И Github, и Gitlab уже знают, как отображать файлы в формате markdown, поэтому у вас будет доступная для просмотра и поиска документация без каких-либо дополнительных усилий.
Если вам нужно что-то более навороченное, то mdBook очень хорошо подходит для отображения этой документации.
Лучше всего начать с любого места
Возможно, есть и другие способы написания документации. Сосредоточьтесь на этой неделе на этом. Вы скажете себе спасибо через пару недель, если вам придется изменить код, который вы написали сегодня, если вы где-то написали документацию по нему.
Понравилась эта статья?
Присоединяйтесь к моей рассылке Short Ruby News, чтобы получать еженедельные обновления Ruby. Также ознакомьтесь с моей книгой LintingRuby, написанной в соавторстве, чтобы узнать больше об автоматизированных проверках кода. Другие ресурсы для изучения Ruby можно найти на сайте rubyandrails.info.