Висячие комментарии
5 декабря 2008



Знаки препинания оптически гораздо легче букв. Они физически не могут конкурировать с ними по плотности и требуют оптической компенсации. Такое свойство знаков пунктуации известно всем, кот увлекается типографикой или, тем более, занимается ей профессионально.


Одним из способов компенсации легковесности знаков препинания является висячая пунктуация. Смысл приёма заключается в вынесении пунктуационных знаков за линию набора; граница текста становится ровной; читать такой текст в разы удобней и приятней.

Совершенно очевидно, что необходимость оптической компенсации, в большинстве случаев, не зависит от того, какой конкретно текст набирается. Научное издание, журнал, газета — висячая пунктуация всем будет к лицу.

И тем не менее, в одной из областей человеческой деятельности, где набираются сотни и тысячи страниц текста ежедневно, висячая пунктуация не то что не используется, о ней вообще никто не задумывается.

Речь идет о программном коде, а точнее о комментариях к нему. Никто вообще не думает о какой-либо типографике в коде, а между тем, её законы никто не отменял. Набранный без учета оптических свойств знаков препинания комментарий будет смотреться также неряшливо, как и текст книги, сверстанной нерадивым или ленивым дизайнером.
Артемий Лебедев, Ководство
(Москва, Издательство Студии Артемия Лебедева, 2007. ISBN 978-5-98062-008-0), с. 234
§ 120. Висячая пунктуация



Из вышесказанно следует простое правило: при наборе комментариев к любому программному коду должна использоваться висячая пунктуация.




{Не знаю почему, но таблицы, в которые осуществляется вставка,
надо очистить. Так делал предыдущий автор, а мы люди подневольные.
*Порядок удаления, кстати, важен; tableRequisites всегда в конце.}
 ClearTable(tableAddresses);
ClearTable(tablePhones);
ClearTable(tableRequisites);

{Не знаю почему, но таблицы, в которые осуществляется вставка,
 надо очистить. Так делал предыдущий автор, а мы люди подневольные.
*Порядок удаления, кстати, важен; tableRequisites всегда в конце.}
  ClearTable(tableAddresses);
 ClearTable(tablePhones);
 ClearTable(tableRequisites);

↑ Пример на языке Delphi.
Такие висячие комментарии создают в коде тот же неповторимый кайф, что и висячая пунктуация в тексте. Автор лично использует это прием уже несколько месяцев и ответственно заявляет, что форматировать комментарии таким образом совсем не трудно, а читать — очень приятно.



Николай Товеровский
При использовании материалов ссылка на ksoftware.ru обязательна.

См. также