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

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

использовать комментарии вида @keyword, где keyword - код, определяющий тип комментария. Комментарий @рагат мог бы описывать параметр метода, @version - версию файла, @tbrows - исключения, генерируемые методом, и т. д. Эта методика позволяет применять инструменты для извлечения разных видов информации из файлов исходного кода. Так, для получения документации обо всех исключениях, генерируемых методами программы, вы могли бы выполнить поиск комментариев @throws.

Эта конвенция С++ основана на общепринятой конвенции http: cc2e.com/S259 Javadoc документирования интерфейсов в программах Java

(java.sun.com/j2se/javadoc/). Для других языков вы можете определить собственные соглашения.

Комментирование классов, файлов и программ

Пе1е1феШ1<»1есыякаОформзти- Классы, файлы и программы объединяет то, что все они ровани» классов, файяоа и про- включают много методов: файл или класс должен содержать граш см. рщел 318. Об исполь набор родственных методов, программа содержит ёсс ме-30ВШ1И11 классов см, гпаву 6. тоды. В каждом этом случае цель документирования в том,

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

Общие принципы документирования классов

Создайте перед каждым классом блочный комментарий, описывающий общие атрибуты класса. Учтите при этом следующее.

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

Опишите ограничения класса, предположения о его использовании

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

Прокомментируйте интерфейс класса Может ли другой программист разобраться в использовании класса, не изучив его реализацию? Если нет, инкапсуляция класса подвергается серьезной опасности. Интерфейс класса должен содержать информацию, нужную для использования класса. Конвенция Javadoc требует документирования хотя бы каждого параметра и каждого возвращаемого значения (Sun Microsystems, 2000). Это надо сделать для каждого метода, предоставляемого каждым классом (Bloch, 2001).

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



Общие принципы документирования файлов

Создайте в начале файла блочный комментарий, описывающий содержание файла.

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

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

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

Укажите в блочном комментарии свои имя/фамилию, адрес электронной почты и номер телефона При работе над крупными проектами большое значение имеют такие факторы, как авторство и ответственность за конкретные фрагменты исходного кода. В небольших проектах (реализуемых с участием менее 10 человек) годятся методики совместной разработки, при которых все члены группы в равной степени отвечают за все разделы кода. Разработка более крупных систем требует, чтобы программисты специализировались на разных областях кода, что делает совместное владение кодом нереальным.

В этом случае сведения об авторстве нужно включать в листинг Они позволят другим программистам, работающим над кодом, узнать кое-что о стиле программирования и связаться с автором кода, если им понадобится помощь. В зависимости от того, над чем вы работаете (над отдельными методами, классами или программами), сведения об авторстве следует включать на уровне методов, классов или программ.

Включите в файл тег версии Многие инструменты управления версиями вставляют сведения о версии в файл. Например, система CVS автоматически расширяет символы:

$Id$

в комментарий:

$1с1: ClassName.java.v 1.1 2004/02/05 00:36:43 ismene Exp $

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

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



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

(с) Copyright 1993-2004 Steven С. McConnell. All Rights Reserved.

Присвойте файлу имя, характеризующее его содержание Как правило, имя файла должно быть тесно связано с именем открытого класса, содержащегося в файле. Так, если класс называется Employee, файл следует назвать Employee.cpp. Некоторые языки, например Java, требуют, чтобы имя файла соответствовало имени класса.

Книжная парадигма документирования программ

Дополнительные севдвнйл Зто Самые опытные программисты соглашаются с тем, что ме-

обсужденае основано на рабо- тодики документирования, описанные в предыдущем раз-

тах «Ttie Book Paradigm for деле, полезны. Достоверных научных данных о полезности

Improved Maintenance* (Oman каждой из методик все еще мало, однако при объединении

and Cook 1990а) й typographic методик их эффективность не вызывает сомнений. Style Is More Than Cosmetic*

(Oman and Cook, 19Ш), Похо- В 1990 году Пол Оман и Кертис Кук опубликовали резуль-

жий подробный анализ см. в таты двух исследований «Книжной парадигмы (Book Рага-

.Human Factors and Typography digm)» документирования (Oman and Cook, 1990a, 1990b). for More Readable Proorams»

/D 1/ AM itmm С)ни искали СТИЛЬ кодирования, который поддерживал бы оаесквг апи iviarcus, iy"0),

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

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

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

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

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

«Перекрестные ссылки» - это карты перекрестных ссылок в коде, включающие номера строк.

Низкоуровневые методики, опираясь на которые Оман и Кук воспользовались преимуществами сходств между книгой и листингом, похожи на методики, описанные в главе 31 и этой главе.



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