Добавил:
Upload Опубликованный материал нарушает ваши авторские права? Сообщите нам.
Вуз: Предмет: Файл:
Скачиваний:
14
Добавлен:
17.04.2015
Размер:
40.73 Кб
Скачать

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

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

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

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

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

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

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

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

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

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

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

Чтобы качество комментариев было выше, нужно учитывать, каковы реальные потребности человека и как он читает код. Комментарии в коде – не единственная помещаемая в нем документация. Комментарии – не спецификации. Это не проектные документы.

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

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

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

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

Комментарии C помещаются в блоках между комбинациями /* и */ и могут занимать произ-вольное количество строк. В C++, C99, C# и Java есть, кроме того, однострочные коммента-рии, следующие за //.

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

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

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

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

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

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

Я бы сравнил это с искусством хорошего музыканта. Если вы играете в оркестре, то ваша задача не в том, чтобы при каждом удобном случае поднимать как можно больше шума. Чем больше вы играете на своем инструменте, тем сложнее становится суммарное звучание и тем хуже музыка. Точно так же излишние комментарии запутывают код. Хорошему музыканту не нужно думать о том, когда же ему остановиться и дать возможность сыграть кому то другому. Хороший музыкант играет свою партию, только когда она вносит что то ценное в музыку. Смысл в том, чтобы сыграть тот минимум, который необходим для создания лучшего звучания. Простор составляет красоту. Комментарии нужно писать лишь тогда, когда они составляют действительную ценность.

Учитесь писать ровно столько комментариев, сколько необходимо. Отдайте предпочтение качеству, а не количеству. Тот, кто будет читать ваши комментарии, может прочесть сам код, по этому стремитесь в большей мере использовать для документирования сам код, а не комментарии. Во всяком случае к коду больше доверия –комментарии имеют скверную привычку врать. Рассматривайте операторы в своем коде как первый уровень комментиро-вания и сделайте их самодокументируемыми.

На деле хорошему коду комментарии не нужны, потому что в нем все должно быть очевидно. Если вы даете функциям такие имена, как f() и g(), то неизбежно приходится описывать их в комментариях, но какая нибудь someGoodExample() не требует никаких комментариев. Сразу

видно, что это имя функции, дающей хороший пример. Не пожалейте труда, чтобы ваш код не требовал поддержки в виде уймы комментариев.

Чем меньше комментариев, тем реже встретятся плохие комментарии.