В предыдущей статье о философии комментирования кода я отметил, что лучшие комментарии – это те, которые не нужны. Позвольте мне пояснить эту мысль. Сначала вы должны стремиться сделать свой код максимально простым для понимания, не полагаясь на комментарии как на костыль. Только тогда, когда код уже невозможно сделать более понятным, стоит добавлять комментарии.
Полезно помнить о своей аудитории при написании кода. В классической книге «Структура и интерпретация компьютерных программ», впервые опубликованной в 1985 году, прямо в предисловии сказано:
Программы должны писаться для людей, чтобы их читали, и лишь второстепенно – для машин, чтобы они их выполняли.
Ноутон поднимает аналогичную тему в своём классическом эссе 1984 года о литературном программировании:
Изменим наше традиционное отношение к разработке программ: вместо того, чтобы думать, что наша главная задача — указать компьютеру, что делать, сосредоточьтесь на том, чтобы объяснить людям, чего мы хотим от компьютера. Практик литерного программирования может рассматриваться как эссеист, главной заботой которого является изложение и совершенство стиля. Такой автор, вооружённый тезаурусом, тщательно выбирает названия переменных и объясняет значение каждой из них. Он или она стремится к программе, которая будет понятна благодаря тому, что концепции представлены в порядке, наиболее подходящем для человеческого восприятия, используя сочетание формальных и неформальных методов, усиливающих друг друга.
Если вы будете писать код так, чтобы он был ориентирован в первую очередь на других программистов, а во вторую – на компилятор, то потребность в дополнительных комментариях значительно уменьшится. Пример отличного использования комментариев в качестве костыля:
Это фрагмент кода из хорошо финансируемой закрытой системы, которая используется в рабочей среде много лет.
float _x = abs(x - deviceInfo->position.x) / scale;int directionCode;if (0 < _x & x != deviceInfo->position.x) { if (0 > x - deviceInfo->position.x) { directionCode = 0x04 /*left*/; } else if (0 < x - deviceInfo->position.x) { directionCode = 0x02 /*right*/; }}
Это эквивалентно следующему, более читаемому коду, с исправлением ошибки.
static const int DIRECTIONCODE_RIGHT = 0x02;static const int DIRECTIONCODE_LEFT = 0x04;static const int DIRECTIONCODE_NONE = 0x00;int oldX = deviceInfo->position.x;int directionCode= (x > oldX)? DIRECTIONCODE_RIGHT: (x < oldX)? DIRECTIONCODE_LEFT: DIRECTIONCODE_NONE;
Обратите внимание, что больше комментариев не всегда означает более читаемый код. Не в этом примере. Комментарии в приведённом выше фрагменте – если вы их вообще заметили – только ещё больше запутывают код. Иногда меньше комментариев делает код более понятным. Особенно если это заставляет вас использовать осмысленные имена символов вместо всего прочего.
Хотя существует почти бесконечное количество возможностей рефакторинга и упрощения кода, чтобы исключить необходимость комментариев, объяснять себя исключительно через код тоже имеет свои ограничения.
Каким бы простым, лаконичным и понятным ни был ваш код, невозможно, чтобы код сам документировал себя полностью. Одни лишь комментарии заменить нельзя. Спросите Джефа Рэскина:
Код не может объяснить, почему написана программа, и почему выбран именно этот метод. Код не может обсудить причины выбора тех или иных альтернативных подходов. Например:
/* Бинарный поиск оказался медленнее алгоритма Бойера-Мура для интересующих нас наборов данных, поэтому мы использовали более сложный, но быстрый метод, даже несмотря на то, что эта задача с первого взгляда не подходит для применения методов строкового поиска.*/
То, что совершенно очевидно одному разработчику, может быть абсолютно непонятно другому разработчику, у которого нет контекста. Подумайте над этим советом по комментированию:
Вы, возможно, знаете, что
$string = join('',reverse(split('',$string)));
переворачивает строку, но насколько сложно добавить строчку
# Reverse the string
в ваш Perl-файл?
Действительно. Это совсем не сложно. Код может сказать вам, как работает программа; комментарии могут объяснить, почему она работает именно так. Старайтесь не обделять своих коллег-разработчиков ни в одном из этих аспектов.
Код показывает, как это работает, комментарии объясняют, почему это так
В предыдущей статье о философии комментирования кода я отметил, что лучшие комментарии – это те, которые не нужны. Позвольте мне пояснить эту мысль. Сначала вы должны стремиться сделать свой код максимально простым для понимания, не полагаясь на комментарии как на костыль. Только тогда, когда код уже невозможно сделать более понятным, стоит добавлять комментарии.
Полезно помнить о своей аудитории при написании кода. В классической книге «Структура и интерпретация компьютерных программ», впервые опубликованной в 1985 году, прямо в предисловии сказано:
Ноутон поднимает аналогичную тему в своём классическом эссе 1984 года о литературном программировании:
Если вы будете писать код так, чтобы он был ориентирован в первую очередь на других программистов, а во вторую – на компилятор, то потребность в дополнительных комментариях значительно уменьшится. Пример отличного использования комментариев в качестве костыля:
Это фрагмент кода из хорошо финансируемой закрытой системы, которая используется в рабочей среде много лет.
Это эквивалентно следующему, более читаемому коду, с исправлением ошибки.
Обратите внимание, что больше комментариев не всегда означает более читаемый код. Не в этом примере. Комментарии в приведённом выше фрагменте – если вы их вообще заметили – только ещё больше запутывают код. Иногда меньше комментариев делает код более понятным. Особенно если это заставляет вас использовать осмысленные имена символов вместо всего прочего.
Хотя существует почти бесконечное количество возможностей рефакторинга и упрощения кода, чтобы исключить необходимость комментариев, объяснять себя исключительно через код тоже имеет свои ограничения.
Каким бы простым, лаконичным и понятным ни был ваш код, невозможно, чтобы код сам документировал себя полностью. Одни лишь комментарии заменить нельзя. Спросите Джефа Рэскина:
То, что совершенно очевидно одному разработчику, может быть абсолютно непонятно другому разработчику, у которого нет контекста. Подумайте над этим советом по комментированию:
Вы, возможно, знаете, что
$string = join('',reverse(split('',$string)));переворачивает строку, но насколько сложно добавить строчку
# Reverse the stringв ваш Perl-файл?
Действительно. Это совсем не сложно. Код может сказать вам, как работает программа; комментарии могут объяснить, почему она работает именно так. Старайтесь не обделять своих коллег-разработчиков ни в одном из этих аспектов.