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

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

Производительность не является разумной причиной отказа от комментирования Одним периодически повторяющимся атрибутом технологических волн, обсуждавшихся в разделе 4.3, являются интерпретируемые среды, в которых комментарии вызывают чувствительное снижение производительности. В 1980-х это относилось к программам, написанным на Basic. В 1990-х - к asp-страницам. Сейчас похожая проблема связана с кодом JavaScript и другим кодом, который нужно передавать по сети.

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

Оптимальная плотность комментариев

По данным Кейперса Джонса, исследования, проведенные в IBM, показа-J[] ли, что понятность кода достигала пика при одном комментарии примерно на 10 операторов. Как меньшая, так и более высокая плотность комментариев осложняла понимание кода (Jones, 2000).

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

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

32.5. Методики комментирования

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

Комментирование отдельных строк

Если код хорош, необходимость комментирования отдельных строк возникает редко. Есть две возможных причины комментирования строки кода:

строка довольно сложна и потому требует объяснения;

строка когда-то содержала ошибку, и вы хотите отметить это.

Вот некоторые советы по комментированию отдельных строк кода.

Избегайте комментариев, высосанных из пальца Много лет назад я слышал историю о программисте, которого подняли с постели исправить неработав-шую программу С автором программы, который к тому времени уже оставил компанию, связаться было невозможно. Программист раньше не работал с этой про-



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

MOV АХ, 723h ; R. I. Р. L. V. В.

Поломав над ним голову всю ночь, программист в итоге все исправил и пошел домой спать. Несколько месяцев спустя он встретился с автором программы на конференции и узнал, что комментарий означал «Rest in peace, Ludwig van Beet-hoven» (Покойся в мире, Людвиг ван Бетховен). Бетховен умер в 1827 году, которому соответствует шестнадцатеричное значение 723. Необходимость использования значения 723h не имела никакого отношения к комментарию. &%@*?*%~!!!

Комментарии в концах строк и связанные с ними проблемы

Пример кода с комментариями в концах строк (Visual Basic)

For employeeld = 1 To employeeCount

GetBonus( employeeld, employeeType, bonusAmount ) If employeeType = EmployeeType Manager Then

PayManagerBonus( employeeld, bonusAmount ) полная оплата Else

If employeeType = EmployeeType Programmer Then If bonusAmount >= MANAGER APPROVAL LEVEL Then

PayProgrammerBonus( employeeld, StdAmtO ) стандартная оплата

Else

PayProgrammerBonus( employeeld, bonusAmount ) полная оплата End If End If End If Next

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

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

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



Не используйте комментарии в концах строк, относящиеся к одиночным строкам С комментариями в концах строк связаны не только практические, но и концептуальные проблемы. Вот пример набора комментариев в концах строк:

Пример бесполезных комментариев в концах строк (С++)

Здесь комментарии просто повторяют код.

memoryToInitialize = MemoryAvailable(); получение объема доступной памяти pointer = GetMemory( memoryToInitialize ); получение указателя на память ZeroMemory( pointer, memoryToInitialize ); обнуление памяти

FreeMemory( pointer ); освобождение памяти

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

Не используйте комментарии в концах строк, относящиеся к нескольким строкам кода Если комментарий в конце строки относится к нескольким строкам, форматирование не позволяет узнать, к каким именно:

ШПример непонятного комментария в конце строки (Visual Basic)

For rateldx = 1 to rateCount Вычисление цен со скидкой

LookupRegularRate( rateldx, regularRate )

rate( rateldx ) = regularRate * discount( rateldx ) Next

Суть данного комментария ясна, но что он комментирует? Чтобы узнать, относится ли комментарий к отдельной команде или целому циклу, придется прочитать и комментарий, и код.

Когда использовать комментарии в концах строк?

Ниже описаны три разумных причины использования комментариев в концах строк.

Перекрестная тшл О других используйте комментарии в концах строк для пояс-

аспектах использования ком- «« объявлений данных Комментарии в концах строк ттрть а концах строк для полезны для аннотирования объявлений данных, потому что птштт объявлений данных с ними не связаны проблемы, характерные для аналогичен, ниже подрщел «Коммвн- ix комментариев кода, если, конечно, строки имеют дотирование объявлений данных, статочную длину При 132 символах в строке вы обычно можете написать выразительный комментарий около каждого объявления данных:

Пример объявлений данных с хорошими комментариями в концах строк (Java)

int boundary = 0; верхний индекс отсортированной части массива

String insertVal = BLANK; элемент, вставляемый в отсортированную часть массива

int insertPos = 0; индекс вставки элемента в отсортиров. часть массива



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