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

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)

Переменная Смысл ----- -----

xPos .......... Координата X (в метрах)

yPos .......... Координата Y (в метрах)

ndsCmptng...... Требуется ли вычисление? {- О, если вычисление требуется;

=1, если вычисление не требуется)

ptGrdTtl....... Общее число точек

ptValMax....... Максимальное значение в точке

psblScrMax..... Максимально возможная сумма

Если вы подумали про точки (.....), вы совершенно правы! Красиво, конечно, но список хорош и без них. Точки затрудняют изменение комментариев, и, если есть выбор (а он обычно есть), комментарии лучше сделать правильными, чем красивыми.

Вот пример другого популярного стиля, трудного в сопровождении: Пример стиля комментирования, который трудно поддерживать (С++)

* класс: GigaTron (GIGATRON.СРР)

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

* дата: 4 июля 2014 года

* Методы, управляющие самым передовым инструментом оценки кода. *

* Точкой входа в эти методы является метод EvaluateCode(), *

* расположенный в конце файла. *

Это симпатичный блочный комментарий. По оформлению ясно, что весь блок - единое целое; начало и окончание блока также бросаются в глаза. Что неясно, так это легкость изменения этого блока. При его изменении почти наверняка придется заново выстраивать аккуратные столбцы звездочек. На практике это означает, что из-за слишком большого объема работы такой комментарий поддержи-



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

Пример стиля комментирования, который легко поддерживать (С++)

класс: GigaTron (GIGATRON.СРР)

автор: Дуайт К. Кодер дата: 4 июля 2014 года

Методы, управляющие самым передовым инструментом оценки кода. Точкой входа в эти метода является метод EvaluateCocle(), расположенный в конце файла.

Вот стиль, особенно трудный в сопровождении:

Пример стиля комментирования,

который трудно поддерживать (Visual Basic)

настройка перечисления Color +--------------------------+

настройка перечисления Vegetable +------------------------------+

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

На подобных рассуждениях основан и популярный совет использовать в Java и С++ синтаксис для однострочных и синтаксис/*... */ - для более длинных комментариев:

Пример использования разного синтаксиса комментирования с разными целями (Java)

Это короткий комментарий.

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



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

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

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

Используйте для сокращения времени, уходящего на щщ О jp комментирование, процесс программирования с псев- программирования с псевдо-докодом Формулирование кода в виде комментариев пе- кодом т. адеу 9. ред его написанием обеспечивает целый ряд преимуществ.

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

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

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

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



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