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

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

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

Комментирование управляющих структур

Панкисшяссыша Об управ* Обычно самое подходящее место для комментирования ттщ структурах см. также управляющей структуры - предшествующие ей строки. Если разделы 31.3 и 314 и главы с это оператор или блок case, вы можете пояснить в ком-14 по 10. ментарии условие и результаты. Если это цикл, можно ука-

зать его цель.

Пример комментирования цели управляющей структуры (С++)

- Цель цикла.

-> копирование символов входного поля до запятой

while ( ( *inputString , ) && ( *inputString != END OF STRING ) ) { *fielcl = *inputString; field++; inputString++;

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

•->} while - копирование символов входного поля afield = END OF STRING;

if ( *inputString !- END OF STRING ) {

- Цель цикла. Положение комментария ясно говорит, что переменная inputString устанавливается с целью использования в цикле.

пропуск запятой и пробелов для нахождения следующего входного поля inputString++;

while ( ( *inputString ) && ( *inputString != END OF STRING ) ) { inputString++;

} if - конец строки

Опираясь на этот пример, можно дать несколько советов по комментированию управляющих структур.

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



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

} for clientlndex - обработка записей всех клиентов

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

Пример использования комментариев, иллюстрирующих вложенность (Java)

for ( tablelndex = 0; tablelndex < tableCount; tablelndex++ ) { while ( recordlndex < recordCount ) {

if ( !IllegalRecordNumber( recordlndex ) ) {

Эти комментарии сообщают, какая управляющая структура завершается.

} if } while } for

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

Рассматривайте комментарии в концах циклов как предупреждения о сложности кода Если цикл настолько сложен, что в его конце нужен комментарий, подумайте, не упростить ли цикл. Это же правило относится к сложным операторам if и блокам case.

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

Комментирование методов

с комментариями методов связан одни из самых худших крастнад ашща О фо ма

советов, который дается в типичных учебниках по програм- щшшт шщш т. радел

мированию. Многие авторы советуют независимо от размера зи. о создании аыоококане-

или сложности метода нагромождать перед его началом це- ственных шшт главу 7. лыс информационные баррикады:

Пример монолитного натуралистичного пролога метода (Visual Basic)

********

Имя: CopyString

Цель: Этот метод копирует строку-источник (источник)

в строку-приемник (приемник).



Алгоритм: Метод получает длину "источника", после чего поочередно

копирует каждый символ в "приемник". В качестве индекса массивов "источника" и "приемника" используется индекс цикла. Индекс цикла/массивов увеличивается после копирования каждого символа.

Входные данные: input Копируемая строка

Выходные данные: output Строка, содержащая копию строки "input" Предположения об интерфейсе: нет История изменений: нет

Автор: Дуайт К. Кодер

Дата создания: 01.10.04

Телефон: (555) 222-2255

SSN: 111-22-3333

Цвет глаз: Зеленый

Девичья фамилия: -

Группа крови: АВ-

Девичья фамилия матери: -

Любимый автомобиль: "Понтиак Ацтек"

Персонализированный номер автомобиля: "Tek-ie"

Это глупо. Метод CopyString тривиален и скорее всего включает не более пяти строк кода. Комментарий совершенно не соответствует объему метода. Цель и алгоритм метода высосаны из пальца, потому что трудно описать что-то настолько простое, как CopyString, на уровне детальности между «копированием строки» и самим кодом. Предположения об интерфейсе и история изменений также бесполезны - эти комментарии только занимают место в листинге. Фамилия автора дополнена избыточными данными, которые можно легко найти в системе управления ревизиями. Заставлять указывать всю эту информацию перед каждым методом - значит подталкивать программистов к написанию неточных комментариев и затруднять сопровождение программы. Эти лишние усилия не окупятся никогда.

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

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

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



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