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

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

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

Пример комментария, играющего роль «заголовка раздела» (Java)

создание нового счета

if ( accountType AccountType.NewAccount ) {

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

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

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

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

Пример документирования сюрприза (С++)

for ( element = 0; element < elementCount; element++ ) { Для деления на 2 используется операция сдвига вправо. Это сокращает время выполнения цикла на 75%. elementList[ element ] = elementList[ element ] » 1;

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

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



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

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

Проведите различие между общими и детальными комментариями

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

Пример проведения различия между общим и детальными комментариями при помощи подчеркивания - не рекомендуется (С++)

- Общий комментарий подчеркивается.

У/ копирование всех строк таблицы, кроме строк, подлежащих удалению

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

-> определение числа строк в таблице

- ...ни здесь.

•-> маркирование строк, подлежащих удалению

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

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



Лучше предварять детальные комментарии многоточием:

Пример проведения различия между общим и детальными комментариями при помощи многоточий (С++)

- Общий комментарий форматируется как обычно.

-> копирование всех строк таблицы, кроме строк, подлежащих удалению

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

•"/Z ... определение числа строк в таблице - ...и здесь.

-> . .. маркирование строк, подлежащих удалению

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

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

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

Допустим, вы обнаружили, что библиотечный метод WnteData( data, numltems, blockSize) работает неверно, если blockSize имеет значение 500. Метод прекрасно обрабатывает значения 499, 501 w все остальные, которые вы когда-либо пробовали, но имеет дефект, проявляющийся, только когда параметр blockSize равен 500. Напишите перед вызовом WriteDataQ, почему вы создали специальный случай для этого значения параметра. Вот как это могло бы выглядеть:

Пример документирования кода, предотвращающего ошибку (Java)

blockSize = optimalBlockSize( numltems, sizePerltem );



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