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

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

32.4. Советы по эффективному комментированию

Пока существуют плохо опрвде- следующий метод?

ленные цели» странные ошибки . /, v

и нереалистичные сроки, будт Загадочный метод номер один (Java)

сущесшеать и Настоящие про- У g п от i до num

грашисты, желающие немедленно приступить к Решению Проблемы и оставляющие документацию на потом. Да адрае-

current = 1; previous = 0; sun = 1;

ствует Фортран] ( int i - 0; i < num; i++ ) {

За Пост (EdPost) System.out. println( "Sum = " + sum ); sum = current + previous; previous = current; current = sum;

Этот метод вычисляет первые пит чисел Фибоначчи. Стиль кодирования этого метода чуть лучше, чем стиль метода, указанного в начале главы, но комментарий неверен, и если вы слепо доверяете комментариям, то, пребывая в блаженном неведении, пойдете в неверном направлении.

А что скажете по поводу этого метода? Загадочный метод номер два (Java)

присваивание переменной "product" значения переменной "base" product = base;

цикл от 2 до "num"

for ( int i = 2; i num; i++ ) {

умножение "base" на "product"

product = product * base;

System.out.println( "Product = " + product );

Этот метод возводит целое число base в целую степень пит. Комментарии в этом методе верны, но они не говорят о коде ничего нового. Это просто более многословная версия самого кода.

Наконец, еще один метод: Загадочный метод номер три (Java)

вычисление квадратного корня из Num с помощью аппроксимации Ньютона-Рафсона г = num / 2;

while ( abs( г - (num/r) ) > TOLERANCE ) { г = 0.5 * ( г + (num/r) );

System.out.println( "r = " + r );



Этот метод вычисляет квадратный корень из пит. Код неидеален, но комментарий верен.

Какой метод понять было легче всего? Все они написаны довольно плохо - особенно неудачны имена переменных. По сути эти методы иллюстрируют достоинства и недостатки внутренних комментариев. Комментарий Метода 1 неверен. Комментарии Метода 2 просто повторяют код и потому бесполезны. Только комментарий Метода 3 оправдывает свое существование. Наличие плохих комментариев хуже, чем их отсутствие. Методы 1 и 2 лучше было бы оставить вообще без комментариев.

В следующих подразделах я приведу советы по написанию эффективных комментариев.

Виды комментариев

Комментарии можно разделить на шесть категорий, описанных ниже. Повторение кода

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

Объяснение кода

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

Маркер в коде

Этот тип предназначен не для того, чтобы оставаться в коде. Такая пометка указывает программисту на то, что работа еще не выполнена. Некоторые разработчики делают маркеры синтаксически некорректными (например,), чтобы о невыполненной работе напомнил компилятор. Другие включают в комментарии определенный ряд символов, не приводящий к ошибке компиляции и служащий для поиска нужного фрагмента.

Мало что может сравниться с чувствами программиста, получившего от заказчика сообщение о проблеме в коде и увидевшего во время отладки что-нибудь вроде:

return NULL; ****** НЕ СДЕЛАНО! ИСПРАВИТЬ ДО ВЫПУСКА ПРОГРАММЫ!!!

Если вы поставили заказчикам дефектную программу, это плохо; если же вы знали, что она дефектна, это просто ужасно.

Стандартизуйте стиль комментариев-маркеров, иначе одни программисты будут использовать для этого символы, другие - !!!!!!, третьи - 7ВД а четвертые - что-то еще. Применение разных нотаций повышает вероятность ошибок при механическом поиске незавершенных фрагментов кода или вообще делает его невозможным. Стандартизация стиля маркирования позволяет сделать механичес-



кий поиск незавершенных фрагментов одним из действий контрольного списка перед выпуском программы и предотвратить проблему ИСПРАВИТЬ ДО ВЫПУСКИ . Некоторые редакторы поддерживают теги «to do» и позволяют легко искать их.

Резюме кода

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

Описание цели кода

Комментарий уровня цели объясняет намерения автора кода. Такие комментарии относятся скорее к уровню проблемы, чем к уровню ее решения. Например, комментарий:

-- получение информации о текущем сотруднике

является комментарием цели, тогда как:

-- обновление объекта employeeRecord

является резюмирующим комментарием, сформулированным в терминах решения.

Шестимесячное исследование, проведенное в IBM, показало, что программисты, отвечавшие за сопровождение программы, «чаще всего говорили, что труднее всего было понять цель автора кода» (Fjelstad and Hamlen, 1979). Различие между комментариями цели и резюмирующими не всегда очевидно и обычно не играет особой роли. В этой главе вы найдете массу примеров комментариев цели.

Информация, которую невозможно выразить в форме кода

Кое-какую информацию, не выразимую в форме кода, все-таки нужно включить в программу Эта категория комментариев включает уведомления об авторских правах и конфиденциальности данных, номера версий и другие детали, замечания о структуре кода, ссылки на релевантные документы требований или архитектуры, ссылки на Интернет-ресурсы, соображения по оптимизации, комментарии, нужные таким инструментам редактирования, как Javadoc, Doxygen и т. д.

К трем видам комментариев, приемлемых в готовом коде, относятся резюмирующие комментарии, комментарии цели и информация, не выразимая в форме кода.

Эффективное комментирование

Эффективное комментирование отнимает не так много времени. Избыток комментариев не менее плох, чем недостаток, а оптимальной середины можно достичь без особых проблем.

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



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.0024