Я прочитал несколько статей о «хороших комментариях», написал несколько, прочитал технические книги о «хороших комментариях» и работаю над проектом JavaScript, где все должно быть прокомментировано (jsdoc). Я изменил свое мнение по этому вопросу.
⚠️ Читайте больше моих статей о технике и бизнесе в моем личном блоге! ⚠️
Самостоятельное документирование кода
То, что я узнал из своего опыта и прочитанного, можно подытожить названием этого поста.
Лучшие комментарии — это те, которые мы не пишем.
Когда вы чувствуете необходимость написать комментарий, это обычно потому, что ваш код не настолько ясен и чист, как должен быть.
Сравните это
function main() {
let imageName = 'test.png'
// Get the extension off the image filename
let pieces = imageName.split('.')
let extension = pieces.pop()
}
Комментарий сам по себе не является чем-то плохим. Разработчик может решить, что они могут понадобиться нам позже, чтобы лучше понять код. Он ставит комментарий, это хорошо.
Но это выглядит как оправдание: «Мой код уродлив/сложен, но он не так уж плох, я объясню это в комментарии» вместо того, чтобы очистить его.
function main() {
let imageName = 'test.png'
let extension = getFileExtension(imageName)
}
Имя функции уже должно отвечать на вопрос, что делает та или иная часть кода. Почему бы не использовать эту возможность?
Слишком большое количество комментариев душит код
Как было сказано выше, в моем текущем проекте мы должны документировать все. Все должно быть закомментировано с помощью jsdoc.
В этом нет ничего плохого. Но в итоге большинство написанных комментариев — это комментарии, используемые исключительно для прохождения тестов. Они избыточны и бесполезны.
/**
* Get the extension of the file
*
* @param {string} filename - The filename
* @return {string} the extension of the file
*/
function getFileExtension(filename) {
let pieces = imageName.split('.')
return pieces.pop()
}
Скажите, что в этом комментарии есть информация, которую вы не поняли, читая код? Ее нет.
Наоборот, то, что функция возвращает расширение файла, повторяется трижды: один раз в названии функции, один раз в ее описании и один раз в теге @return.
Какова дополнительная ценность этого комментария? Никакой.
Когда вы постоянно видите бесполезные комментарии, ваш мозг учится их игнорировать. Вы, вероятно, уже сталкивались с этим: в проекте, где много комментариев и большинство из них похожи на те, что мы видели выше, в итоге вы перестаете видеть и читать комментарии.
К сожалению, несколько интересных комментариев теряются в море бесполезных и оказываются не такими полезными, как хотелось бы.
Покрытие кода документацией
Как и в случае с модульными тестами, сейчас существует множество инструментов для измерения покрытия кода комментариями по документации.
И как для юнит-тестов, вы быстро поддадитесь искушению достичь 100% покрытия.
И что касается модульных тестов, я не уверен, что это то, что стоит делать. Для модульных тестов высокое покрытие ненадежно и не является доказательством качества; для документации высокий процент покрытия контрпродуктивен и душит код.
Заставляя разработчиков писать документацию везде, мы заставляем их писать отстойную документацию.
Там, где код чист, комментарий будет бесполезен, и ваш мозг вскоре его проигнорирует. Там, где код грязный, разработчик будет использовать комментарий как оправдание для того, чтобы не обновлять свой код.
Я пишу меньше комментариев
… и это не плохо. Код легче читать. Это заставляет меня делать мой код как можно более понятным: таким образом, код становится чище. Читатели будут обращать больше внимания на те немногие комментарии, которые я пишу.
Единственная проблема, с которой я сталкиваюсь сегодня, возникает в контексте проекта с автоматически генерируемой публичной документацией. Как избежать избыточности и при этом убедиться, что документация, сгенерированная на основе моего комментария, является полной.
Чтобы копнуть глубже, вот более свежий пост, который глубже объясняет концепцию/идею, представленную здесь. Она написана после отзывов и вопросов читателей:
- La documentation sera toujours utile