Pull to refresh

Комментировать или не комментировать?

Perfect code
«Ясно, что на некотором уровне комментарии должны быть полезны. Думать иначе означало бы полагать, что понятность программы не зависит от того, сколько информации о ней уже известно читающему программу человеку. Б. Шейл.»
Действующие лица:
ФРАСИМАХ Неопытный пурист теории, который верит всему, что читает.
КАЛЛИКЛ Закаленный в боях представитель старой школы — «настоящий»
программист.
ГЛАВКОН Молодой, самоуверенный, энергичный программист.
ИСМЕНА Опытная разработчица, уставшая от громких обещаний и просто
желающая найти несколько работающих методик.
СОКРАТ Мудрый опытный программист.

Мизансцена:
Завершение ежедневного собрания группы
— Желает ли кто-то обсудить еще что-нибудь, прежде чем мы вернемся к работе? — спрашивает Сократ.
— Я хочу предложить стандарт комментирования для наших проектов, — говорит расимах. — Некоторые наши программисты почти не комментируют свой код, а всем известно, что код без комментариев нечитаем.
— Ты, должно быть, еще менее опытен, чем я думал, — отвечает Калликл. — Комментарии — это академическая панацея, и любому, кто писал реальные программы, известно, что комментарии затрудняют чтение кода, а не облегчают. Естественный язык менее точен, чем Java или Visual Basic, и страдает от избыточности, тогда как операторы языков программирования лаконичны и попадают в самое яблочко. Если кто-то не может написать ясный код, разве ему удастся написать ясные комментарии? Кроме того, комментарии устаревают при изменениях кода.
Доверяя устаревшим комментариям, ты сам себе роешь яму.

— Полностью согласен, — вступает в разговор Главкон. — Щедро прокомментированный код читать труднее, потому что в этом случае читать приходится больше. Мало
того, что я должен читать код, так мне нужно читать еще и кучу комментариев!
— Подождите минутку, — вставляет свои две драхмы Йемена, ставя чашку кофе.
— Конечно, злоупотребление комментариями возможно, но хорошие комментарии
ценятся на вес золота. Мне приходилось сопровождать код как с комментариями,
так и без них, и, будь у меня выбор, я бы предпочла первый вариант. Не думаю, что
нам нужен стандарт, заставляющий писать один комментарий на каждые х строк
кода, но побудить всех программистов комментировать код не помешает.
— Если комментарии — пустая трата времени, почему все их используют, Калликл? — спрашивает Сократ.
— Или потому, что таково требование, или потому, что человек прочитал где-то о
пользе комментариев. Ни один программист, когда-либо задумавшийся об этом, не пришел к выводу, что комментарии полезны.

— Йемена считает, что они полезны. Она уже три года сопровождает твой код без
комментариев и чужой код с комментариями. Ее мнение ты уже слышал. Что ты
скажешь на это?
— Комментарии бесполезны, потому что они просто повторяют код в более многословной…
— Подожди, — прерывает Калликла Фрасимах. — Хорошие комментарии
не повторяют код и не объясняют его. Они поясняют его цель. Комментарии должны объяснять намерения программиста на более высоком уровне абстракции, чем код.
— Верно, — соглашается Йемена. — Если я ищу фрагмент, который мне нужно изменить или исправить, я просматриваю комментарии. Комментарии, повторяющие код, на самом деле бесполезны, потому что все уже сказано в самом коде. Когда
я читаю комментарии, я хочу, чтобы они напоминали оглавление книги. Комментарии должны помочь мне найти нужный раздел, а после этого я начну читать
код. Гораздо быстрее прочитать одно предложение на обычном языке, чем анализировать 20 строк кода на языке программирования.
Йемена наливает себе вторую чашку кофе.

— Мне кажется, что люди, отказывающиеся писать комментарии, A) думают, что
их код понятнее, чем мог бы быть, B) считают, что другие программисты гораздо сильнее интересуются их кодом, чем есть на самом деле, C) думают, что другие программисты умнее, чем есть на самом деле, D) ленятся или E) боятся, что
кто-то другой узнает, как работает их код.
— В этом смысле очень помогли бы обзоры кода, Сократ, — продолжает Йемена.
— Если кто-то утверждает, что комментарии писать не нужно, и получает во время обзора кучу вопросов — если сразу несколько коллег спрашивают его: „Что происходит в этом фрагменте твоего кода?" — он начинает писать комментарии. Если программист не дойдет до этого сам, его руководитель сможет заставить его писать комментарии.
— Я не утверждаю, Калликл, что ты ленишься или боишься, что кто-то другой поймет твой код. Я работала с твоим кодом и могу сказать, что ты — один из лучших
программистов компании. Но будь чуточку добрее, а? Мне было бы легче сопровождать твой код, если бы ты писал комментарии.

— Но это пустая трата времени, — не сдается Калликл. — Код хорошего программиста должен быть самодокументирующимся: все, что нужно знать другим программистам, должно быть в самом коде.
— Нет! — Фрасимах вскакивает со стула. — В коде и так уже есть все, что нужно
знать компилятору! С таким же успехом можно было бы сказать, что все, что нужно знать другим программистам, уже есть в двоичном исполняемом файле! Если
бы мы только были достаточно умны, чтобы уметь читать его! Информации о том,
что программист собирался сделать, в коде нет.
Фрасимах замечает, что вскочил с места, и садится.
— Сократ, это немыслимо. Почему мы спорим о важности комментариев? Во всех
книгах, которые я читал, говорится, что комментарии полезны и что на них не стоит экономить. Мы зря теряем время.
— Успокойся, Фрасимах. Спроси у Калликла, как давно он программирует.

— Действительно, как давно, Калликл?
— Ну, я начал с системы Акрополь IV где-то 15 лет назад. Думаю, что я стал свидетелем рождения и гибели примерно десятка крупных приложений. А еще в десятке проектов я работал над крупными компонентами. Две из этих систем включали более полумиллиона строк кода, так что я знаю, о чем говорю. Комментарии совершенно бесполезны.
Сократ бросает взгляд на более молодого программиста.
— Как говорит Калликл, с комментариями действительно связано много проблем,
и ты не поймешь это, пока не приобретешь больше опыта. Если комментировать
код неграмотно, комментарии не просто бесполезны — они вредны.
— Они бесполезны, даже если комментировать код грамотно, — заявляет Калликл.
— Комментарии менее точны, чем язык программирования. Лично я думаю, что
лучше вообще их не писать.

— Постой, — говорит Сократ. — Йемена согласна с тем, что комментарии менее
точны, но она утверждает, что комментарии поднимают программиста на более
высокий уровень абстракции, а все мы знаем, что абстракция — один из самых
эффективных инструментов, имеющихся в нашем распоряжении.
— Я с этим не согласен, — заявляет Главкон. — Нам следует концентрироваться
не на комментариях, а на читабельности кода. При рефакторинге большинство
моих комментариев исчезает. После рефакторинга мой код может включать 20
или 30 вызовов методов, не нуждающихся в каких бы то ни было комментариях.
Хороший программист способен определять цель автора по самому коду; к тому
же какой толк в чтении о чьей-то цели, если известно, что код содержит ошибку?
Главкон умолкает, удовлетворенный своим вкладом в беседу. Калликл кивает.
— Похоже, вам никогда не приходилось изменять чужой код, — говорит Йемена.
Калликл делает вид, что его очень заинтересовали плитки на потолке.

— Почему бы вам не попробовать прочитать собственный код через шесть месяцев или год после его написания? Вы можете развивать и навык чтения кода, и навык
его комментирования. Никто не заставляет вас выбирать что-то одно. Если вы читаете роман, вам, может, и не нужны названия глав. Но при чтении технической
книги вам, наверное, хотелось бы иметь возможность быстро найти то, что вы ищете.
Тогда мне не пришлось бы переходить в режим сверхсосредоточенности и читать
сотни строк кода для нахождения двух строк, которые я хочу изменить.
— Хорошо, я понимаю, что возможность быстрого просмотра кода была бы удобной, — говорит Главкон. Он видел некоторые из программ Исмены, и они не оставили его равнодушным. — Но как быть с другим утверждением Калликла — что
комментарии устаревают по мере изменений кода? Я программирую лишь пару
лет, но даже я знаю, что никто не обновляет свои комментарии.

— Ну, и да, и нет, — говорит Йемена. — Если вы считаете комментарии неприкосновенными, а код подозрительным, у вас серьезные проблемы. На самом деле несоответствие между комментарием и кодом обычно говорит о том, что неверно
и то, и другое. Если какие-то комментарии плохи, это не означает, что само комментирование плохо. Пойду налью себе еще чашку кофе.
Йемена выходит из комнаты.
— Мое главное возражение против комментариев, — заявляет Калликл, — в том,
что они тратят ресурсы.
— Можете ли вы предложить способ минимизации времени написания комментариев? — спрашивает Сократ.
— Проектирование методов на псевдокоде, преобразование псевдокода в комментарии и написание соответствующего им кода, — говорит Главкон.
— ОК, это сработает, если комментарии не будут повторять код, — утверждает Калликл.
— Написание комментария заставляет вас лучше подумать над тем, что делает ваш
код, — говорит Йемена, возвращаясь с новой чашкой кофе. — Если комментарии
писать трудно, это означает, что код плох или вы недостаточно хорошо его понимаете. В обоих случаях вы должны поработать над кодом еще, так что время, потраченное на его комментирование, не пропадает — оно указывает вам на необходимую работу.
— Хорошо, — подводит итоги Сократ. — Не думаю, что у нас остались еще вопросы. Похоже, Йемена сегодня была самой убедительной. Мы будем поощрять комментирование, но не будем относиться к нему простодушно. Мы будем выполнять
обзоры кода, чтобы все поняли, какие комментарии на самом деле полезны. Если
у вас возникнут проблемы с пониманием кода другого программиста, подскажите ему, как он может его улучшить.

Стив Макконнелд
Tags:комментирование кода
Hubs: Perfect code
Total votes 14: ↑10 and ↓4 +6
Views1.1K
Game Code
August 15, 202160,500 ₽XYZ School
Рефакторинг кода на Java
July 26, 202125,000 ₽Luxoft Training
Факультет дизайна
June 21, 2021236,988 ₽GeekBrains
Профессия iOS-разработчик
June 21, 202190,000 ₽SkillFactory
Профессия Аналитик данных
June 21, 202169,000 ₽SkillFactory

Top of the last 24 hours