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

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

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

for i = 1 to maxElmts - 1 - исправлена ошибка #А423 01.10.05 (scm)

Наверное, написать такой комментарий после ночного сеанса отладки программы приятно, но в итоговом коде им не место. Их лучше включать в системы управления версиями. Комментарии должны объяснять, почему код работает сейчас, г не почему он когда-то не работал.

Используйте комментарии в концах строк для обозна- цщ q yg, чения концов блоков В комментариях в концах строк д mwm строк, служа-полезно отмечать окончание объемных блоков кода - на- щих дли обозначения концов пример, циклов while или операторов Подробнее об этом блоков см. ниже подраздел см. ниже. «Комментирование управляю-

щих структур».

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

Комментирование абзацев кода

Большинство комментариев в хорошо документированной программе состоят из одного-двух предложений и описывают абзацы кода:

Пример хорошего комментария абзаца кода (Java)

перемена корней местами OldRoot = root[0]; root[0] = root[1]; root[1] = OldRoot;

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

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

Шрщтш ееыбка Зтот код,

Пример неэффективного комментария (Java) выполняющий простой поиск

символа в строке, служит только

/* проверка символов строки "inputSt ring", пока не будет в качестве примера. 8 реальном

обнаружен ,(одв вы использовали бы дяя

знак доллара или пока не будут проверены все символы шго естроеиныебиблиотечные

*/ функции Java. О важности no-

done = false; ниманйя возможностей языка

naxLen = inputString. length(); см. подраздел «Читайте!» раз-

i - 0;

дела 33.3.



while ( Idone && ( i < maxLen ) ) { if ( inputString[ i ] $ ) { done = true;

else { i++;

Прочитав код, можно понять, что цикл ищет символ $, и это полезно отразить в комментарии. Недостаток этого комментария в том, что он просто повторяет код и ничего не говорит о его цели. Следующий комментарий чуть лучше:

поиск символа $ в строке inputString

Этот комментарий лучше потому, что он говорит, что целью цикла является поиск символа S. Но мы все еще не знаем причину поиска символа S - иначе говоря, более глубокую цель цикла. Вот комментарий, который еще лучше:

поиск терминального символа слова команды ($)

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

При комментировании на уровне цели полезно подумать о том, как бы вы назвали метод, выполняющий то же самое, что и код, который вы хотите прокомментировать. Если каждый абзац кода имеет одну цель, это несложно: примером может служить комментарий в предыдущем фрагменте кода. Имя FindCommand-WordTerminatorQ было бы вполне приемлемым именем метода. Другие варианты - FindSInlnputStringQ и CbeckEacbCharacterlnlnputStrUntilADollarSignlsFoundOrAll-CbaractersHaveBeenCbeckedQ - по очевидным причинам являются плохими (или некорректными) именами. Опишите суть кода как имя соответствующего метода, не используя сокращений и аббревиатур. Это описание и будет комментарием, и скорее всего он будет относиться к уровню цели.

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

Пример хорошего кода с хорошим комментарием (Java)

поиск терминального символа слова команды foundTheTerminator - false; commandStringLength = inputString.length(); testCharPosition = 0;



while ( ! foundTheTerminator && ( testCharPosition < cofTimandStringLength ) ) { If ( inputString[ testCharPosition ] COMMAND WORD TERMINATOR ) { foundTheTerminator = true;

j- Эта переменная содержит результат поиска.

-> terminatorPosition = testCharPosition;

else {

testCharPosition = testCharPosition + 1;

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

Наконец, этот код следовало бы выделить в метод с именем щвтшшш\тОвынш вроде FindCommandWorcnerminatorO Аналогичный коммента- jj, фрагмента кода в отдель-рий также полезен, но при изменении ПО комментарии уста- «ый метод см. также подраздел ревают и становятся неверными чаще, чем имена методов. «Извлечение метода из друго-

. го метода» раздела 24.3.

Придумывая комментарии абзаца, стремитесь ответить на вопрос «почему?», а не «как?» Комментарии,

объясняющие, «как» что-то выполняется, обычно относятся к уровню языка программирования, а не проблемы. Цель операции почти невозможно выразить в таком комментарии, поэтому он часто оказывается избыточным. Разве следующий комментарий сообщает что-то такое, чего не ясно из самого кода?

Пример комментария, отвечающего на вопрос «как?» (Java)

если флаг счета равен нулю if ( accountFlag ==0 ) ...

Нет, не сообщает. А этот?

Пример комментария, отвечающего на вопрос «почему?» (Java)

если создается новый счет if ( accountFlag ==0 ) ...

Этот комментарий гораздо лучше, так как он говорит что-то, чего нельзя понять, исходя из самого кода. Код также можно улучшить, заменив О на элемент перечисления с выразительным именем и уточнив имя переменной. Вот самая лучшая версия этого кода и этого комментария:

Пример дополнения хорошего комментария хорошим стилем программирования (Java)

если создается новый счет

if ( accountType AccountType.NewAccount ) ...

Когда код достигает такого уровня читабельности, ценность комментариев становится сомнительной. В нашем случае после улучшения кода комментарий стал



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