В программировании постоянно обсуждают использование комментариев. Эрика Садун, выдающийся блогер и автор книги на Swift, в прошлом много писала о комментариях.
Недавно Эндрю Уорнер написал статью, в которой говорится, что написание комментариев в коде часто является устаревшим и даже вредным для вашей кодовой базы.
Комментарии распадаются. Они не компилируются и никогда не будут выполняться во время выполнения. Если они устареют или станут некорректными, ни один тест не провалится, и ни один пользователь не будет жаловаться. Программисты работают вокруг них из-за страха, что кому-то может понадобиться этот комментарий или он может принести пользу в будущем, подталкивая их далеко после того, как они будут полезны (если вы даже можете утверждать, что они были полезны с самого начала).
Эрика написала отличный ответ на статью, подчеркнув важность комментариев в вашей кодовой базе.
Комментарии не просто скрывают плохой дизайн и код. Они документируют процесс создания правильного кода, поддерживая чтение и модификацию в будущем. Хорошие комментарии уменьшают умственные усилия, необходимые читателям каждый раз, когда они просматривают ваш источник, позволяя им больше сосредоточиться на конкретных задачах, таких как «как добавить эту функцию», а не «что, черт возьми, здесь происходило».
Я полностью согласен с Эрикой и хотел подчеркнуть один конкретный способ, которым комментарии помогают читателям вашего кода.
Комментарии нужны не только для плохого кода
Раньше я работал в основном со старшим разработчиком, намного более умным, чем я, и у нас почти не было комментариев в нашем коде. У нас есть опыт работы с iOS, и мы обычно не работаем с одним и тем же файлом. Из-за этого мы не часто сталкивались с проблемами читабельности кода.
Однако в нашем последнем проекте мы наняли нового сотрудника, опытного Java-разработчика, который все еще изучает Swift и iOS. Я впервые заметил, что наш код временами довольно нечитабелен.
Выполняя парное программирование и наблюдая, как он проходит через нашу кодовую базу, я мог видеть, что ему было трудно понять, что было частью Swift или iOS, и каков был наш код. Также казалось, что он мог легко понять метод и то, что он делает, но у него были проблемы с пониманием того, как все части сочетаются друг с другом.
Это особенно верно для более сложного кода в UIViewController. Из-за природы кода пользовательского интерфейса различные части, такие как анимация, методы жизненного цикла, стили и представление, смешаны вместе и взаимозависимы.
Здесь я заметил, что наша пословица «комментарии предназначены только для плохого кода» развалилась. Читать код сложно, независимо от того, насколько он хорош. Выяснить, как все эти части сочетаются друг с другом, - непростая задача. Наша задача как разработчиков - упростить чтение кода.
Обеспечение контекста
При написании статей я всегда обращаю особое внимание на вступление, которое собираюсь написать. Его цель - установить контекст и побудить читателя понять, что искать в статье.
Если вы читаете статью без первых нескольких абзацев, вам придется потратить первые несколько минут, пытаясь понять, в чем цель этой статьи. Это учебник? Это новостная статья? Это реклама?
В этих нескольких первых абзацах вы сосредотачиваете свое внимание на попытке проанализировать саму статью, а не ее содержание. У вас также нет контекста, необходимого для понимания того, что пытается сказать статья.
Статья - это больше, чем сумма ее абзацев. То, как эти абзацы сочетаются друг с другом, устанавливает общую нить и достигает цели, которую вы хотите достичь.
То же самое и с кодом. Класс - это больше, чем сумма его общедоступных методов. Каждый класс имеет обязанности (точка) и вписывается вместе с кодом, окружающим его ( контекст). Как бы мы ни старались, использование классов всегда будет влиять на то, как мы их пишем. Ни один метод не изолирован полностью от call-сайта. У каждого класса есть контекст, в который он вписывается.
При чтении кода, не имея контекста того, что делает класс, вы должны прочитать его пару раз, чтобы выяснить, какие внутри него зависимости и как все это сочетается друг с другом. Как и статья без вступления, это тратит время читателя и может привести к ошибкам, когда другие разработчики (или будущее-вы) попытаются что-то изменить.
Вот почему я определенно предлагаю большой блок комментариев для каждого класса (или сложного метода), который, по сути, описывает цель этого кода. Каждый фрагмент текста требует вступления, почему классы должны отличаться?
Всегда помните, что код гораздо больше читается, чем его пишут. Оптимизируйте для читателя, а не для писателя.
Марин - разработчик iOS в COBE, блогер на marinbenc.com и студент компьютерных наук в FERIT, Осиек. Ему нравится программировать, узнавать о вещах, а потом писать о них, кататься на велосипедах и пить кофе. В основном, однако, он просто вызывает сбои SourceKit. У него есть пухлый кот по имени Амиго. Не он сам писал эту биографию.
