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

Отчего я вновь комментирую код приложений на Ruby/Rails

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

Здравствуйте, я — разработчик программного обеспечения на Ruby / Rails и я комментирую свой (а с недавних пор ещё и Сторонний) код. Голос из зала, видимо, крикнул бы «Здравствуй, разработчик!»

Много лет назад мне казалось явственным устоявшееся суждение специалистов и гуру разработки, которое обыкновенно выражается приблизительно так: «Если код требует комментария — это дрянной код, его необходимо переписать/отрефакторить/упростить/уменьшить». Т.е. привести его к виду, комментариев и пояснений не требующему. В целом, данный подход довольно универсален и работает во многих случаях. Многие мои знакомые веб-разработчики никогда не комментируют свой код и считают это абсолютно типичным явлением, даже если работают в команде. Видимо, сказывается миф о простоте Ruby, такой простоте, которая делает код внятным даже стороннему. Впрочем, мой индивидуальный навык и некоторые эпизоды командной разработки веб-приложений уговорили меня в том, что существуют обстановки и поводы уделять комментариям и документированию кода огромнее внимания и времени, чем обыкновенно уделяет разработчик.

Сразу же предупрежу, что в Интернете, возможно, есть уйма статей и постов, излагающих какую-либо точку зрения об искусстве написания кода, о правилах и рекомендациях для всякого определенного языка программирования. Их все я, безусловно же, не могу знать, следственно экскурса в историю вопроса не будет. Будет только мой индивидуальный рассказ о моём личном навыке.

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

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

  • Когда код написан неквалифицированно: слишком длинно (допустимо, разработчик нехорошо знает стандартную библиотеку и писал много лишнего кода сам) либо слишком трудно (perl-style, однострочные цепочки функций длиной больше 5-ти функций подряд)
  • Когда код включает в себя редкоиспользуемые либо нехарактерные для данного ЯП способы и приёмы

И всё! В этих случаях, подлинно, отменнее такой код переделать. Переделать, убедится, что код стал короче, яснее, внятнее для коллег и… наконец-то написать комментарии! И вот я теснее добрался до того места, где и буду объяснять свои идеи.

Пояснение для Идеи № 1: «О трудности кода адекватно может судить только его автор».

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

Что же будет, если один либо двое программистов уйдут из команды, в иной план, в иную студию либо легко в отпуск? Видимо, на их место будут взяты один и два других разработчика, которым дадут код, дадут задачи и… и всё. Заранее, HR-администратор спросит у них, умеют ли они «разбираться в чужом коде» и «трудиться в команде», а они, безусловно же, ответят, что умеют. И опять прибывшие окажутся один на один с кодом и коллегами, которые быть может и рады отвечать на вопросы «а отчего тут так…» либо «а для чего там это…», но это отвлекает от работы. Следственно разработчик вынужден «разбиться с планом». число рабочего времени, потраченного на «выполнение» своим мозгом чужого кода с целью пройти по нему и осознать, что он делает — ужасает. Поясню на примере.

Предположим себе функцию, как бы такой:

def update
   list = current_user.lists.update(params[:id], params[:list])
end

С точки зрения правила о простоте кода, тут легко эдем. Комментировать здесь нечего, одна строка, абсолютно никаких трудностей. Впрочем, предположим себе, что params формируется не примитивный формой на странице, а с поддержкой кода на Javascript в Backbone.js, что lists — это на самом не lists, а оставшееся от прошлой команды наименование и модель эта сейчас всюду в тестах именуется Things, что на before_save этой модели навешена функция, которая берёт некие поля и создаёт отложенное задание, которое парсит, согласно данным этих полей некие URL’ы (допустимо, без контроля ошибок HTTP-протокола), Дабы потом сберечь полученные результаты в инойтаблице. А изредка вызывает exception’ы и шлёт сообщения о них… куда-то… на сайт сбора ошибок, куда программисту дадут доступ, как только он сам напомнит. А вовсе другой контроллер (API, скажем) отдаст значения этих полей ajax’ом в Backbone’овскую View. Кстати, дозволено ещё уточнить, что данная функция должна рендерить образец, вначале пропуская его через парсер RABL, формируя там JSON, абсолютно непохожий на первоначальное содержимое list, тот, что Things. Ну и для полного комплекта уточним, что трудиться это должно на хостинге с какими-нибудь ограничениями, к примеру, без доступа к cron’у. И с качестве СУБД применяется NoSQL.

Приведённый пример — это не неправда, не особое усложнение. В реальных планах бывает и огромнее шагов в выполнении какой-то функции приложения. Но неизменно только сам автор кода может знать, труден его код либо нет. Задача в том, что человек, которому необходимо реализовать в этом приложении новую функциональность неминуемо должен будет своим мозгом взамен интерпретатора «исполнить» примерно всю имеющуюся базу кода. Либо он будет это сделать ДО начала написания кода, на что потратит время, которое администратору придётся как-то обосновать в отчётах, либо он будет делать это в процессе написания кода, что есть самый дрянный вариант. Отчего? А потому что итоги такой работы будут весьма низкокачественными и вернувшийся из отпуска автор всё равно всё переделает. А вы уплатите новичку за то, что он разбирался с планом, а в выводе всё равно пользы не принёс.

Есть и иная Зачастую встречающаяся задача.

В плане N функциональность M обыкновенно реализуется с поддержкой XYZ. Не зная кода всецело либо не прочитав документации к плану, описывающей конструкцию и используемые XZY, разработчик не может знать, X, Y либо Z применяется ли теснее либо нет. И если нет — отчего не применяется. Не существует программиста, тот, что может сразу же начать трудиться и создавать новое в неизвестном ему плане, это миф о «крутости разработчика». Лучшее, к чему может привести сходственная обстановка — разработчик сделает свою задачу так, как может, отдаст на code review и получит код обратно с комментарием «Для чего сделал так, чай у нас для этого принято применять [список каких-то технологий]» либо «Для чего сделал так, чай дозволено было так: [описание сущностей, узнать существование которых самосильно немыслимо (скажем, присутствие триггеров либо функций в БД на production-сервере]»

Так что же я предлагаю, теснее давным-давно пора спросить читателю. Раньше каждого, делайте с кодом, над которым трудитесь, несколько примитивных пророческой:

  • Описывайте то, как работает данный код. Непременно, хоть и коротко, в начале всякого файла, содержащего класс, описывайте, что он реализует. Перед способами класса коротко описывайте, что способ получает и что должен сделать в конце своей работы, коротко описывайте цепочку, по которой пройдут данные. Так же в файлах-модулях. Комментируйте вычисляемые механически значения и назначения создаваемых миграциями полей. В случае длинной цепочки вызовов функций (длиннее трёх) — описывайте цепочку, что вызывает что, правда бы легко последовательность.
  • Ведите в всяком файле блок TODO, в одном и том же месте, хоть сразу позже объявления класса либо модуля.
  • Ведите в всяком файле блок IN_WORK (назовите как желательно Вам), в котором пишите о том, какие места в данный момент подвергаются переделке/рефакторингу/устарели и взамен них необходимо применять BLABLA из класса XYZ.
  • Непременно описывайте все факты, присутствие которых невозможно вывести из имеющейся документации!

Для последнего пункта приведу пример: если ваш план несовместим, скажем, с MySQL, а разработчик потратил полдня, пытаясь развернуть план именно на этой СУБД, не вздумайте сказать ему «Мы же не поддерживаем MySQL!». В результат вы услышите в лучшем случае «А отчего я об этом не знал?». И если вы скажете этому парню фразу «А отчего ты не спросил?» — можете быть уверены. что в вашем плане теснее существуют крупные задачи с документированием и это теснее наносит вам урон. чай никто из нас не знает точного списка каждого, что он не знает!

Спасибо за внимание и пускай ваш код будет неизменно ясен, примитивен и задокументирован.

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

Оставить комментарий
Форум phpBB, русская поддержка форума phpBB
Рейтинг@Mail.ru 2008 - 2017 © BB3x.ru - русская поддержка форума phpBB