Я читал « Философию дизайна программного обеспечения» Джона Остерхаута.
В одном месте книги он дает такой совет по поводу комментариев кода:
К сожалению, многие комментарии не особо полезны. Наиболее частая причина заключается в том, что комментарии повторяют код: всю информацию в комментарии можно легко вывести из кода рядом с комментарием.
Затем он приводит пример, чтобы проиллюстрировать то, о чем он говорит:
// Add a horizontal scroll bar
hScrollBar = new JScrollBar(scrollBar, HORIZONTAL);
add(hScrollBar, BorderLayout.SOUTH);
// Add a vertical scroll bar
vScrollBar = new JScrollBar(JScrollBar.VERTICAL);
add(vScrollBar, BorderLayout.EAST);
// Initialize the caret-position related values
caretX = 0;
caretY = 0;
caretMemX = null;
Аргумент против подобных комментариев состоит в том, что они «на том же уровне детализации», что и сам код. Код ясен по своему назначению, поэтому комментарии излишни.
Далее Джон заявляет, что для того, чтобы быть полезными, комментарии должны обеспечивать детализацию уровня, не выводимую из кода:
Комментарии дополняют код, предоставляя информацию на другом уровне детализации. Некоторые комментарии предоставляют информацию на более низком, более подробном уровне, чем код; эти комментарии добавляют точности, разъясняя точное значение кода. Другие комментарии предоставляют информацию на более высоком, более абстрактном уровне, чем код; эти комментарии предлагают интуицию, например, обоснование кода или более простой и абстрактный способ размышления о коде.
Я думаю, что это очень справедливое и разумное объяснение того, что делает комментарии в коде полезными или нет.
И все же у меня есть некоторые мнения.
Если кто-то скажет, что комментарий не добавляет никакой ценности, я бы спросил: для кого?
Лично мне никогда не нравился совет о том, что написание очевидных комментариев - плохая практика - вероятно, потому, что я все время пишу очевидные комментарии.
Комментарии, которые находятся на том же уровне детализации, что и код, могут быть бесполезны для вас как беглого читателя и писателя кода, но они предназначены для кого-то вроде меня, который все еще пытается понять, как читать и писать код. Я считаю их полезными при написании кода, потому что они позволяют мне заявить о своем намерении (на простом английском языке), перевести его в код, затем сравнить утверждения и посмотреть, насколько хорошо я достиг своей цели.
Конечно, если вы сотрудничаете с командой людей, вам нужно понять, как вместе писать код. А это может означать компромисс и удаление комментариев, которые полезны для вас, но отвлекают других (вы всегда можете сделать это в конце процесса создания кода).
Возможно, это очевидное утверждение, но если написание «бесполезных» комментариев к коду помогает вам, то они не бесполезны. Они наоборот: полезны.
Это напоминает мне то время, когда я выучил испанский. Люди всегда говорили: «Не переводите слово в слово в уме. Пусть слова означают то, что они означают, на их естественном языке». Тем не менее, когда я впервые выучил язык, я бы поступил именно так:
В конце концов я стал достаточно бегло говорить там, где мне не нужно было делать это руководство, пошаговый, построчный перевод в голове. Слова имели собственное значение на их родном языке. В тот момент я понял, что бесполезно (для меня) переводить на английский в уме.
Развивая этот пример немного дальше, представьте это как код:
// What is your name?
¿Como te llamas?
// My name is Jim
Me llamo Jim.
// Where is the library?
¿Donde esta la biblioteca?
Учитывая то, что люди говорят о комментариях к коду, вы можете подумать, что такие комментарии бесполезны. Из книги Джона:
Может ли кто-нибудь, кто никогда не видел кода, написать комментарий, просто взглянув на код рядом с комментарием? Если да ... то комментарий не упрощает понимание кода.
Помогают ли эти комментарии облегчить понимание кода? Ну, это зависит от того, кого вы спросите.
Сказать, что комментарии к коду бесполезны, - это наше суждение, как бегло читающие код. Он игнорирует ценность комментариев для кого-то менее беглого, чем вы, кто либо читает, либо пишет код.
Если вы не считаете себя свободно владеющим языком, вы можете извлечь большую пользу из комментариев, которые другие называют бесполезными, очевидными или избыточными, потому что они помогают вам перевести то, с чем вы не знакомы,—другой язык—на то, что вы есть, например, английский.
И комментарии могут служить совершенно другой цели, когда их читают, а не когда пишут. Это почти два разных вида деятельности.
Поэтому, когда кто-то называет определенный стиль комментирования кода бесполезным, спросите себя: для кого? Конечно, вы должны помнить о коде, который вы вносите в группы людей, но особенно в отдельных проектах: если какой-то конкретный комментарий кода полезен, продолжайте делать это