хитрая детализация

АНТОН ПАЛАГИН AKA TONY

Спецвыпуск: Хакер, номер #071, стр. 071-038-2

[настрой табуляцию.]

В настройках своего редактора поставь галочку, которая предписывает ему вместо символа табуляции вставлять определенное число пробелов (обычно 4 пробела). Это позволит твоему коду не расползаться, как толпа тараканов, по экрану, если клиенту приспичило открыть твой код в каком-нибудь «кривом» редакторе.

[комментируй «длинные» скобки.]

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

[комментируй объявляемые переменные.]

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

[не старайся комментировать каждую строку.]

Если ты объединяешь строки кода в группы по смыслу, то старайся писать каждой группе строчку, которая описывает, что эта группа делает. Не имеет смысла комментировать каждую строку: старайся все сводить к макроуровню комментариев. Оптимальным считается соотношение строк кода к строкам комментариев — 1/3-1/5.

[используй строчные комментарии.]

Старайся использовать строчные комментарии (предваряющиеся символами //) вместо многострочных (предваряющихся символами /*). В том случае, если ты захочешь закомментировать большой блок кода, существующие комментарии тебе не помешают.

[не путай божий дар с яичницей.]

Никакие комментарии не помогут, если ты используешь трехэтажные программные конструкции, которые так любят маньяки STL. Также не стоит злоупотреблять длинными строками (длиннее 80-100 символов) и длинными именами (равно как и короткими названиями). Переменная с именем the_sign_of_specified_mathematical_operation может довести до колик в животе не одну сотню «читателей» кода. Старайся писать более простой код, так чтобы комментарии его дополняли, а не дублировали. Код сам по себе является самым совершенным и лаконичным комментарием, но только в том случае, если он логичен, последователен и прост.

[используй весь спектр тегов автоматизированной документации.]

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