Заметки на полях

Благодаря этому после загрузки файла с исходным кодом я мгновенно получаю представление о качестве кода и о том, насколько легко будет с ним работать. Когда я вижу достаточное количество зеленого цвета в правой части экрана, у меня улучшается настроение. В противном случае мне хочется заварить себе крепкий кофе, прежде чем двигаться дальше.

Комментарии могут превратить плохой код в хороший, непомерно сложную и непостижимую логику – в чудесный набор прозрачных ал% горитмов. Но не будем преувеличивать – есть вещи поважнее коммен% тариев. Если вы написали действительно хороший код, ваши коммен% тарии служат лишь окончательной отделкой, придающей продукту законченный эстетический вид, а не средством скрыть его изъяны и недостатки.

Хорошие комментарии позволяют избавиться от устрашающего впе% чатления при виде кода. Но это не волшебная приправа, превращаю% щая испорченный продукт во вполне съедобный.

Что есть комментарий в коде?

Это важный раздел! Вопрос может показаться надуманным. Кто же не знает, что такое комментарии в коде? Тем не менее вопрос заслужива% ет бо]льших размышлений, чем может показаться на первый взгляд.

Синтаксически комментарий представляет собой блок исходного тек% ста, который игнорируется компилятором. Поместить в него можно что угодно – хоть имена своих внуков, хоть цвет любимой рубашки; компилятор и глазом не моргнет, встретив такое в файле.1

Семантически комментарии составляют разницу между темной лесной дорогой и хорошо освещенным шоссе. Комментарий – это аннотация лежащего рядом кода. Можно воспользоваться им как маркером, чтобы выделить конкретную область задач, или как средством документиро% вания в заголовке файла. С помощью комментариев можно описать ал% горитм, что поможет программисту, который будет сопровождать код (им можете оказаться вы сами), или разметить границы между функ% циями, что позволит легче ориентироваться в файле исходного кода.

Комментарии предназначены человеку, а не компьютеру. В этом смысле они представляют собой самый гуманистически ориентирован% ный элемент в постройке, которой является программа. Они – как де% коративные кирпичи в сравнении с бетонными блоками. Чтобы каче%

1Разумеется, та штука, которая заглотнет и выплюнет ваши комментарии, в каждом языке своя. В C/C++ есть зверь%препроцессор, который сожрет комментарии перед началом этапа компиляции. В других языках сам ком%

пилятор выкинет комментарии при лексическом анализе. В интерпрети% руемых языках обилие комментариев может замедлить выполнение, по% скольку интерпретатору придется просмотреть имена всех ваших внуков.

ство комментариев было выше, нужно учитывать, каковы реальные потребности человека и как он читает код.

Комментарии в коде – не единственная помещаемая в нем документа% ция. Комментарии – не спецификации. Это не проектные документы. И это не справочники по API.1 Тем не менее они представляют собой важную форму документации, которая всегда физически связана с ко% дом (если кто%нибудь злонамеренно не уничтожит их). Близость их к коду приводит к тому, что комментарии чаще обновляют и чаще чи% тают в контексте. Это механизм внутреннего документирования.

Порядочный программист обязан писать хорошие комментарии.

Как выглядят комментарии?

Конечно же, они зеленые… По крайней мере, у меня.

Комментарии C помещаются в блоках между комбинациями /* и */

имогут занимать произвольное количество строк. В C++, C99, C#

иJava есть, кроме того, однострочные комментарии, следующие за //. В других языках есть аналогичные средства комментирования блока# ми и в строке, но синтаксис иной.

Конечно, это элементарный вопрос. Но в использовании маркеров комментариев встречаются тонкие различия. Ниже мы рассмотрим соответствующие примеры. Однако ко всем системам комментирова% ния, изобретательно использующим тонкие синтаксические разли% чия, следует относиться с осторожностью.

Сколько комментариев требуется?

Сильный текст всегда краткий.

Уильям Странк Мл.

Заботиться следует о качестве комментариев, а не об их количестве, поэтому важен не объем комментариев, а их содержание. О нем будет сказано в следующем разделе.

Тех, кто изучает программирование, заставляют писать комментарии, и в большом количестве. Но слишком обширные комментарии могут быть недостатком – важные фрагменты кода оказываются затерянны% ми среди потока слов. Когда вам приходится продираться через про% странные комментарии, вместо того чтобы читать сам код, качество последнего снижается.

Я бы сравнил это с искусством хорошего музыканта. Если вы играете в оркестре, то ваша задача не в том, чтобы при каждом удобном случае

1Если только вы не пользуетесь технологией, о которой рассказано в разделе

«Грамотное программирование» на стр. 104.