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

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

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

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

Описывайте каждый метод одним-двумя предложе-

Перекрестиав ссылка Удачный

ниями перед началом метода Если вы не можете спи- р важней-

сать метод одним или двумя краткими предложениями, вам, щй аспект документирования

вероятно, следует лучше обдумать роль метода. Если крат- методое (см. раздел 7.3).

кое описание придумать трудно, значит, проект метода не

так хорош. Попробуйте перепроектировать метод. Краткое резюмирующее предложение должно присутствовать почти во всех методах, кроме простых методов доступа Get и Set.

Документируйте параметры в местах их объявления Самый простой способ документирования входных и выходных переменных - написать комментарии после их объявления:

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

public void InsertionSort(

int[] dataToSort, массив элементов, подлежащих сортировке

int firstElement, индекс первого сортируемого элемента (>=0)

int lastElement индекс последнего сортируемого элемента (<= MAX ELEMENTS)

Этот совет - уместное исключение из правила, предписы- перекрестная ссыма О коммен-вающего избегать комментариев в концах строк; такие ком- тариях в KOHiax строк см. выше ментарии крайне полезны при документировании входных подраздел «Комментарии в кон-и выходных параметров. Кроме того, данный случай хоро- Ш строк и связанные с ними шо иллюстрирует полезность выравнивания параметров «робйемы» этого раздела, методов с помощью стандартных отступов, а не отступов в

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

Используйте утилиты документирования кода, такие как Javadoc Если бы предыдущий пример нужно было на самом деле написать на Java, вы могли бы адаптировать код к Javadoc - утилите извлечения документации Java. Тогда



смысл совета «документируйте параметры в местах их объявления» несколько изменился бы, что привело бы к получению такого кода:

Пример документирования входных и выходных параметров для использования Javadoc (Java)

* ... <описание метода> ...

* @рагат dataToSort массив элементов, подлежащих сортировке

* @param firstElement индекс первого сортируемого элемента (>=0)

* @рагап lastElement индекс последнего сортируемого элемента (<= MAX ELEMENTS)

public void InsertionSort( int[] dataToSort, int firstElement, int lastElement

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

Проведите различие между входными и выходными данными Знать, какие данные являются входными, а какие выходными, полезно. При работе с Visual Basic определить это относительно легко, потому что выходным данным предшествует ключевое слово ByRef, а входным - ByVal. Если ваш язык не поддерживает такую дифференциацию автоматически, выразите это при помощи комментариев. Вот пример:

пттсшп сеьшка Порядок "РР проведения различия между входными

этих параметров соответствует " ВЫХОДНЫМИ данНЫМИ (С++)

стандартному порядку, пршш. stringCopy(

щ для методов С.., т шн- / , строка-приемник

фликтует с более общимк т- . /, .

тодикаш (см. подраздел .fit- " строка-источник

редавайте параметры ь поряд-

ке „входные значения mm-

НЯ6МЫ6 аначеййя - выходные

значения"» раздела 7.6). 00 ис- Объявления методов С++ немного хитры, потому что иногда

лольэоваийи конвенции имено- звездочка (*) говорит о том, что аргумент является выходным

вания дпя проведения различия параметром, но очень часто это просто означает, что с пере-

тту входным» и выходными менной легче работать как с указателем. Как правило, лучше данными см. раздел 11.4

идентифицировать входные и выходные параметры явно.

Если ваши методы достаточно коротки и вы поддерживаете ясное различие между входными и выходными данными, документировать статус данных (входной или выходной), наверное, не нужно. Однако если метод более объемен, указание статуса поможет всем, кто будет читать код метода.



Документируйте выраженные в интерфейсе пред- цщщ есыш Другие положения Этот совет можно рассматривать как подмно- щштт ттттш жество других рекомендаций по поводу комментирования, терфейсоа штт см. в раз-Если вы сделали какие-либо предположения о состоянии по- Ав 7,5. Ь тшшщрттщ лучаемых вами переменных (о допустимых и недопустимых ярдаоложений с помоурно уг-значениях, о том, что массивы должны быть отсортирова- „уйтв утверждениТдйя доны, что данные-члены должны быть инициализированы или щттщшпт проверки должны иметь только допустимые значения и т. д.), укажи- предусловий и постусловий» те это или в прологе метода, или в месте объявления дан- раздела 6.2, ных. Этот вид документации должен присутствовать почти в каждом методе.

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

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

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

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

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

Используйте комментарии для маркирования частей программы Некоторые программисты отмечают комментариями те или иные части кода, чтобы их было легче искать. Одна такая методика, принятая в С++ и Java, предполагает, что начало каждого метода отмечается комментарием, начинающимся с символов:

Это позволяет перескакивать с метода на метод или путем поиска символов /*, или автоматически, если такую возможность поддерживает редактор.

Похожая методика заключается в использовании разных маркеров для разных видов комментариев в зависимости от того, что они описывают. Так, в С++ вы могли бы



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