Здравствуйте, я разработчик программного обеспечения Ruby/Rails и комментирую свой (а в последнее время и чужой) код. Голос из зала, вероятно, крикнул бы: «Привет, разработчик!» Много лет назад мне казалось очевидным, что устоявшееся мнение профессионалов и гуру разработки, которое обычно выражается примерно так: «Если код требует комментария — это плохой код, его нужно переписать/рефакторить/упростить».
меньше».
Те.
привести его к виду, не требующему комментариев и пояснений.
В целом этот подход достаточно универсален и работает во многих случаях.
Многие мои знакомые веб-разработчики никогда не комментируют свой код и считают это вполне нормальным, даже если они работают в команде.
Вероятно, это связано с мифом о простоте Ruby, той простоте, которая делает код понятным даже постороннему человеку.
Однако мой личный опыт и некоторые эпизоды командной разработки веб-приложений убедили меня, что существуют ситуации и причины уделять комментированию и документированию кода больше внимания и времени, чем обычно уделяет разработчик.
Сразу предупрежу, что в Интернете наверняка есть немало статей и постов, излагающих ту или иную точку зрения на искусство написания кода, на правила и рекомендации для каждого конкретного языка программирования.
Конечно, я не могу знать их всех, поэтому экскурса в историю вопроса не будет. Будет только мой личный рассказ о моем личном опыте.
Главным тезисом моего рассказа будет: «Только его автор может судить о сложности кода».
Итак, прежде всего, нам необходимо уточнить, когда именно работает правило «Вместо того, чтобы комментировать, измените код так, чтобы комментирование стало ненужным».
Это работает только в нескольких случаях:
- Когда код написан неумело: слишком длинный (возможно, разработчик плохо знает стандартную библиотеку и сам написал много ненужного кода) или слишком сложный (перл-стиль, однострочные цепочки функций длиной более 5 функций подряд) )
- Когда в коде присутствуют редко используемые или нехарактерные для данного языка методы и приемы.
пишите наконец комментарии! И вот я уже дошел до того места, где буду объяснять свои идеи.
Пояснение к Идее №1: «Только ее автор может адекватно оценить сложность кода».
Представим себе команду программистов, состоящую, например, из 5 человек.
С ними работает менеджер и пара дизайнеров.
Команда программистов состоит из одного профессионального и четырех программистов обычного уровня.
Код никто не комментирует. Возможно, есть написанная кем-то короткая инструкция по развертыванию проекта.
Команда не ведет документацию, потому что.
заказчик меняет решения и приоритеты и не очень хочет платить за время, потраченное на составление документации в процессе разработки.
По такому принципу работают многие студии веб-разработки среднего уровня.
Что будет, если один-два программиста уйдут из команды в другой проект, в другую студию или просто в отпуск? Вероятно, на их место возьмут еще одного-двух разработчиков, которым дадут код, поставят задачи и… и все.
Сначала HR-менеджер спросит их, умеют ли они «понимать чужой код» и «работать в команде», и они, конечно же, ответят, что могут. А вновь прибывшие окажутся один на один с кодом и коллегами, которые, возможно, и рады ответить на вопросы «почему здесь так.
» или «почему там так.
», но это отвлекает от работы.
.
Поэтому разработчик вынужден «сломать проект».
Количество рабочего времени, потраченного на «выполнение» чужого кода своим мозгом, чтобы пройтись по нему и понять, что он делает, ужасает. Позвольте мне объяснить на примере.
Представим себе такую функцию:
def update
list = current_user.lists.update(params[:id], params[:list])
end
С точки зрения правила о простоте кода это просто рай.
Тут комментировать нечего, одна строчка, абсолютно никаких сложностей.
Однако давайте представим, что параметры формируются не простой формой на странице, а с помощью Javascript-кода в Backbone.js, который на самом деле является не списками, а именем, оставшимся от предыдущей команды, и эта модель теперь называется Things Everywhere. в тестах видно, что на before_save этой модели есть функция, которая берёт определённые поля и создаёт отложенную задачу, которая парсит по данным этих полей определённые URL (возможно без проверки ошибок по протоколу HTTP), чтобы потом сохранить полученные ответы в другой таблице.
А иногда вызывает исключения и отправляет сообщения о них.
куда-то.
на сайт сбора ошибок, куда программисту будет предоставлен доступ, как только он сам напомнит. А совсем другой контроллер (API, например) будет отправлять значения этих полей с помощью ajax в Backbone View. Кстати, еще можно уточнить, что эта функция должна рендерить шаблон, предварительно пропустив его через парсер RABL, сформировав там JSON, совершенно отличный от исходного содержимого списка, которым является Things. Ну и для полного комплекта уточним, что это должно работать на хостинге с некоторыми ограничениями, например без доступа к cron. А в качестве СУБД используется NoSQL. Приведенный пример не является вымыслом и не является особой сложностью.
В реальных проектах шагов выполнения какой-либо функции приложения больше.
Но только автор кода всегда может знать, сложен его код или нет. Проблема в том, что человеку, которому необходимо реализовать новый функционал в этом приложении, неизбежно придётся «исполнять» почти всю существующую кодовую базу своим мозгом, а не интерпретатором.
Либо он сделает это ДО того, как начнет писать код, что приведет к потере времени, которое менеджеру придется как-то обосновывать в отчетах, либо он сделает это во время написания кода, что является худшим вариантом.
Почему? А потому, что результаты такой работы будут крайне некачественными и автор, вернувшись из отпуска, всё равно всё переделает. И вы будете платить новичку за то, что он разобрался в проекте, но в итоге никакой пользы он все равно не принес.
Есть еще одна распространенная проблема.
В проекте N функциональность M обычно реализуется с помощью XYZ. Не зная всего кода или не прочитав документацию проекта, описывающую структуру и используемые XZY, разработчик не может узнать, используется ли уже X, Y или Z или нет. А если нет, то почему он не используется? Нет программиста, который может сразу приступить к работе и создать что-то новое в незнакомом проекте; это миф о «крутости разработчика».
Лучшее, к чему может привести такая ситуация, — разработчик выполнит свою задачу как умеет, отправит ее на code review и получит код обратно с комментарием «Почему вы это сделали, ведь мы обычно используем [ список некоторых технологий] для этого» или «Почему он это сделал, ведь могло быть так: [описание сущностей, существование которых невозможно выяснить самостоятельно (например, наличие триггеров или функций в база данных на рабочем сервере]" Итак, что я предлагаю, давно пора спросить у читателя.
Прежде всего, сделайте несколько простых вещей с кодом, над которым вы работаете:
- Опишите, как работает этот код. Обязательно, хотя и кратко, в начале каждого файла, содержащего класс, опишите, что он реализует. Перед методами класса кратко опишите, что получает метод и что он должен создать в конце своей работы, кратко опишите цепочку, по которой будут проходить данные.
Также в файлах модулей.
Комментируйте автоматически вычисляемые значения и назначения полей, созданные миграциями.
В случае длинной цепочки вызовов функций (более трех) опишите цепочку того, что что вызывает, хотя бы просто последовательность.
- Пишите блок TODO в каждом файле, в одном и том же месте, даже сразу после объявления класса или модуля.
- В каждом файле держите блок IN_WORK (назовите его как хотите), в котором вы пишете о том, какие места в данный момент редизайнятся/рефакторизируются/устаревают и вместо этого вам следует использовать BLABLA из класса XYZ.
- Обязательно опишите все факты, о наличии которых нельзя судить по имеющейся документации!
что у вашего проекта уже есть серьезные проблемы с документацией, и это уже причиняет вам вред. Ведь никто из нас не знает точного списка всего того, чего он не знает! Спасибо за внимание и пусть ваш код всегда будет понятным, простым и документированным.
Теги: #программирование #ruby onrails #комментирование #ruby #программирование #ruby onrails
-
Все, Что Вам Нужно Знать О Хостингах Блогов
19 Oct, 24 -
Яндекс.метрика Открыла Api
19 Oct, 24 -
В Руках Судьбы
19 Oct, 24 -
Видеокамеры На Флэш-Картах Памяти
19 Oct, 24
