Главная - Литература

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 [259] 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294

/* Следующий код нужен потому, что метод 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

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

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

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



0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 [259] 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294



0.0083