Главная
Блог разработчиков phpBB
 
+ 17 предустановленных модов
+ SEO-оптимизация форума
+ авторизация через соц. сети
+ защита от спама

Пишем документацию для Ruby on Rails планов с поддержкой YARD

Anna | 20.06.2014 | нет комментариев

Добросердечный день, програжители! Нашел, что на сайте нет статьи о том, как дозволено организовать процесс создания документации для Ruby on Rails планов. Поправим эту задачу.

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

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

Теория: для чего писать документацию?

Отвечая легко: Дабы код был внятнее. Вашему коллеге по работе не необходимо будет вас отвлекать и задавать 1000 вопросов, а вам не придется крушить себе голову, припоминая хитросплетения своего же кода. В внятном коде легче обнаружить и истребить баг. Также вам самим будет легче добавить в код новую фичу, которую только что неожиданно придумал клиент либо дизайнер.

Но наилучший комментарий — это тот, тот, что не необходимо писать?

Подлинно необходимо писать такой внятный код, Дабы объем нужных для понимания комментариев к нему был минимальным. Это достигается путем применения переменных с внятными наименованиями, предсказуемой и модульной конструкции кода и так дальше. Я сам прежде усердствовал писать код, не прибегая к комментариям. Но скоро осознал, что потратить две секунды на чтение комментария к коду выигрышнее, чем потратить 5-10 на чтение и осознавание даже самого внятного кода. Как ни верти, а типичным языком передать суть кода дозволено значительно проще и результативнее.

Но писать документацию — это же дюже длинно!

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

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

Практика: структуризированные комментарии YARD

Вначале в своих Ruby on Rails планах я писал комментарии без определенной конструкции. Перед всяким способом лаконично писал, что там происходит. Потом осознал, что было бы комфортно описывать, скажем, параметры, тот, что данный способ принимает; а также то, что он возвращает. Встал вопрос, отчего бы всюду не придерживаться цельного образца комментариев?

Обнаружил гем YARD. Суть его в том, что вы пишите комментарии к своему коду, применяя определенный примитивный синтаксис, чем-то отдаленно напоминающий xml/html. Позже чего вы запускаете команду, которая сделает html файлы, где будет расписан ваш код и документация к нему в комфортном формате. Аналогом выступает гем RDOC, но его синтаксис показался мне больше трудным.

Установим гем

$ gem install yard

либо добавим в Gemfile

 gem 'yard'

и запустим bundle install.

Возьмем приблизительный способ с сайта valiizrashki.ru

def try_to_evacuate(country_id)
  country = Country.find(country_id)
  if country.allows_immigrants?
    evacuate!
    true
  else
    false
  end
end

Способ определяет, дозволено ли иммигрировать в иную страну и эвакуируется. Так и запишем перед объявлением способа в виде комментария.

# Определяет, дозволено ли иммигрировать в иную страну и эвакуируетcode> и напишем там:
-o doc/coffee

 Позже этого при запуске команды в корне плана
$ codo

 у нас создастся документация к coffeescript в папке doc/coffee.

 Готово, вы великолепны!

Завершение


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

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

Проголосовало 16 человек. Воздержалось 3 человека.

 

Источник: programmingmaster.ru

Оставить комментарий
БАЗА ЗНАНИЙ
СЛУЧАЙНАЯ СТАТЬЯ
СЛУЧАЙНЫЙ БЛОГ
СЛУЧАЙНЫЙ МОД
СЛУЧАЙНЫЙ СКИН
НОВЫЕ МОДЫ
НОВЫЕ СКИНЫ
НАКОПЛЕННЫЙ ОПЫТ
Форум phpBB, русская поддержка форума phpBB
Рейтинг@Mail.ru 2008 - 2017 © BB3x.ru - русская поддержка форума phpBB