/* Следующий код нужен потому, что метод WriteDataO содержит ошибку, проявляющуюся, только когда третий параметр равен 500. Значение 500 ради ясности заменено на именованную константу. Ч

if ( blockSize WRITEDATA BROKEN SIZE ) { blockSize = WRITEDATA WORKAROUND SIZE;

WriteData ( file, data, blockSize );

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

Не комментируйте хитрый код - перепишите его Вот один комментарий из проекта, в котором я принимал участие:

Пример комментирования хитрого кода (С++)

ОЧЕНЬ ВАЖНОЕ ЗАМЕЧАНИЕ:

Конструктор этого класса принимает ссылку на объект UiPublication.

Объект UiPublication НЕЛЬЗЯ УНИЧТОЖАТЬ раньше объекта DatabasePublication,

иначе программу ожидает мученическая смерть.

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

Это плохая идея.

Комментирование хитрого кода - как раз то, чего делать не следует. Комментарии не могуг спасти сложный код. Как призывают Керниган и Плоджер, «не документируйте плохой код - перепишите его» (Kernighan and Plauger, 1978).

Исследования показали, что фрагменты исходного кода с большим чис-Jjff I лом комментариев обычно включали максимальное число дефектов и отнимали большую долю ресурсов, уходивших на разработку ПО (Lind and Vairavan, 1989). Ученые предположили, что программисты склонны щедро комментировать сложный код.

Когда кто-то говорит: «Это по-настоящему хитрый код,» - я слышу: «Это по-настоящему плохой код». Если вам что-то кажется хитрым, для кого-то другого это окажется непонятным. Даже если что-то не кажется вам очень уж хитрым, другой человек, который не сталкивался с этим трюком, сочтет его очень замысловатым. Если вы спрашиваете себя: «Хитро ли это?» - это хитро. Всегда можно найти несложный вариант решения проблемы, поэтому перепишите код. Сделайте его несколько хорошим, чтобы нужда в комментариях вообще отпала, а затем прокомментируйте код, чтобы сделать его еще лучше.

Этот совет относится преимущественно к коду который вы пишете впервые. Если вы сопровождаете программу и не имеете возможности переписывать плохой код, комментирование хитрых фрагментов - хороший подход.

Комментирование объявлений данных

Шрщтцгп ссылка О форма- Комментарий объявления переменной описывает аспекты

тированйи данных см. подраа- переменной, которые невозможно выразить в ее имени. Тща-

дел «Размещение обьяадений тельно документировать данные важно: по крайней мере одна

данных» раздела 31.5. Об эф- компания, изучавшая собственные методики, пришла к вы-

фективном шопьшттт- воду, что комментировать данные даже важнее, чем процес-йых см. главы 10-13. от го-ч

сы, в которых эти данные используются (SDC в Glass, 1982).

Указывайте в комментариях единицы измерения численных величин Если число представляет длину, укажите единицы представления: дюймы, футы, метры или километры. Если речь идет о времени, поясните, в чем оно выражено: в секундах, прошедших с 1 января 1980 года, миллисекундах, прошедших с момента запуска программы, или как-то иначе. Если это координаты, напишите, что они представляют (ширину, долготу и высоту) и в чем они выражены (в радианах или градусах), укажите систему координат и т. д. Не предполагайте, что единицы измерения очевидны - для нового программиста они такими не будут. Для кого-то, кто работает над другой частью системы, они такими не будут. После значительного изменения программы они тоже очевидными не будут.

Единицы измерения часто следует указывать в именах переменных, а не в комментариях. Например, выражение вида distanceToSurface = marsLanderAltitude выглядит корректным, тогда как distanceToSurfacelnMeters = marsLanderAltitudelnFeet ясно указывает на ошибку.

Пв»ек1естн1я ссылка Более Указывайте в комментариях диапазоны допустимых

эффективный способ докумен- значений численных величин Если предполагается, что тирования диапазонов допусти- значение переменной должно попадать в некоторый диа-мых значений переменных - пазон, задокументируйте это. Одной из мощных возможно-использование утверждений в языка Ada была возможность указания диапазона до-

начале и в конце метода (т. м м

раздел 8 2) пустимых значений численной переменной. Если ваш язык

не поддерживает такую возможность (а большинство языков ее не поддерживает), используйте для документирования диапазона ожидаемых значений комментарии. Например, если переменная представляет денежную сумму в долларах, укажите, что в вашем случае она должна находиться в пределах от 1 до 100 долларов. Если переменная представляет напряжение, напишите, что оно должно находиться в пределах от 105 В до 125 В.

Комментируйте смысл закодированных значений Если ваш язык поддерживает перечисления (как С++ и Visual Basic), используйте их для выражения смысла закодированных значений. Если нет, указывайте смысл каждого значения в комментариях и представляйте каждое значение в форме именованной константы, а не литерала. Так, если переменная представляет виды электрического тока, закомментируйте тот факт, что / представляет переменный ток, 2 - постоянный, а 3 - неопределенный вид.

Вот пример, иллюстрирующий три предыдущих рекомендации: вся информация о диапазонах значений указана в комментариях:

Пример грамотного документирования объявлений переменных (Visual Basic)

Dim cursorX As Integer горизонтальная позиция курсора; диапазон: L.MaxCols Din cursorY As Integer вертикальная позиция курсора; диапазон: L.MaxRows

Din antennaLength As Long длина антенны в метрах; диапазон: >= 2

Din signalStrength As Integer мощность сигнала в кВт; диапазон: >= 1

Dim characterCode As Integer код символа ASCII; диапазон: 0..255

Dim characterAttribute As Integer 0=Обычный; 1=Курсив; 2=Жирный; 3=Жирный курсив

Dim characterSize As Integer размер символа в точках; диапазон: 4..127

Комментируйте ограничения входных данных Входные данные могут быть получены в риде входного параметра, прочитаны из файла или введены пользователем. Предыдущие советы относятся к входным параметров методов в той же степени, что и к другим видам данных. Убедитесь, что вы документируете ожидаемые и неожиданные значения. Комментарии - это один из способов документирования того, что метод никогда не должен принимать некоторые данные. Задокументировать диапазоны допустимых значений можно также, использовав утверждения, и тогда эффективность обнаружения ввода неверных данных заметно повысится.

Документируйте флаги до уровня отдельных би- щщ 0 уущ, тов Если переменная используется как битовое поле, щу пбрвменных-флагов т, укажите смысл каждого бита: подраздея «Имешваииа пере-

менных статуса» раздела t1.2.

Пример документирования флагов до уровня битов (Visual Basic)

Значения битов переменной statusFlags в порядке от самого старшего бита (MSB) до самого младшего бита (LSB): MSB О обнаружена ли ошибка?: 1=да, 0=нет

1-2 тип ошибки: 0=синтаксич., 1=предупреждение, 2=тяжелая, 3=фатальная

3 зарезервировано (следует обнулить)

4 статус принтера: 1=готов, 0=не готов

14 не используется (следует обнулить) LSB 15-32 не используются (следует обнулить) Dim StatusFlags As Integer

Если бы мы писали этот пример на С++, следовало бы использовать синтаксис битовых полей - тогда значения полей были бы самодокументирующимися.

Включайте в комментарии, относящиеся к переменной, имя переменной

Если какие-то комментарии относятся к конкретной переменной, убедитесь, что вы обновляете их вместе с переменной. Помочь в этом может использование в комментариях имени переменной. Благодаря этому при поиске переменной в коде вы найдете не только ее, но и связанные с ней комментарии.