Руководство по стилю программирования и конструированию по
 Скачать 7.6 Mb.
|
|
ГЛАВА 32 Самодокументирующийся код 791 Документируйте выраженные в интерфейсе пред- положения Этот совет можно рассматривать как подмно- жество других рекомендаций по поводу комментирования. Если вы сделали какие-либо предположения о состоянии по- лучаемых вами переменных (о допустимых и недопустимых значениях, о том, что массивы должны быть отсортирова- ны, что данные-члены должны быть инициализированы или должны иметь только допустимые значения и т. д.), укажи- те это или в прологе метода, или в месте объявления дан- ных. Этот вид документации должен присутствовать почти в каждом методе. Убедитесь, что вы задокументировали используемые глобальные данные. Глобальная переменная — такая же часть интерфейса метода, как и все остальное, но при этом она более опасна, так как иногда не кажется частью интерфейса. Если вы пишете метод и понимаете, что делаете предположение об интерфейсе, немедленно задокументируйте его. Комментируйте ограничения методов Если метод возвращает число, укажите его точность. Если в некоторых условиях результаты вычислений неопределен- ны, задокументируйте эти условия. Если на случай проблем вы реализовали в методе поведение по умолчанию, задокументируйте это поведение. Если предполагает- ся, что метод будет работать только с массивами или таблицами определенных размеров, укажите это. Если вам известны изменения кода, которые могут приве- сти к нарушению работы метода, задокументируйте их. Если при разработке ме- тода возникают сбои, задокументируйте и их. Документируйте глобальные результаты выполнения метода Если метод изменяет глобальные данные, опишите, что именно он делает с ними. Как было сказано в разделе 13.3, изменение глобальных данных минимум на порядок опаснее, чем их простое чтение, поэтому изменять их нужно осторожно, и частью этой осторожности должна быть ясная документация. Если документирование стано- вится слишком обременительным, следуйте обычному подходу — перепишите код, чтобы глобальных данных стало меньше. Документируйте источники используемых алгоритмов Если вы исполь- зовали в коде алгоритм из книги или журнала, укажите источник и номер стра- ницы. Если вы разработали алгоритм сами, укажите, где читатель может найти его описание. Используйте комментарии для маркирования частей программы Некото- рые программисты отмечают комментариями те или иные части кода, чтобы их было легче искать. Одна такая методика, принятая в C++ и Java, предполагает, что начало каждого метода отмечается комментарием, начинающимся с символов: /** Это позволяет перескакивать с метода на метод или путем поиска символов /**, или автоматически, если такую возможность поддерживает редактор. Похожая методика заключается в использовании разных маркеров для разных видов комментариев в зависимости от того, что они описывают. Так, в C++ вы могли бы Перекрестная ссылка Другие соображения относительно ин- терфейсов методов см. в раз- деле 7.5. О документировании предположений с помощью ут- верждений см. подраздел «Ис- пользуйте утверждения для до- кументирования и проверки предусловий и постусловий» раздела 8.2. 792 ЧАСТЬ VII Мастерство программирования использовать комментарии вида @keyword, где keyword — код, определяющий тип комментария. Комментарий @param мог бы описывать параметр метода, @version — версию файла, @throws — исключения, генерируемые методом, и т. д. Эта мето- дика позволяет применять инструменты для извлечения разных видов информа- ции из файлов исходного кода. Так, для получения документации обо всех исклю- чениях, генерируемых методами программы, вы могли бы выполнить поиск ком- ментариев @throws. Эта конвенция C++ основана на общепринятой конвенции Javadoc документирования интерфейсов в программах Java ( java.sun.com/j2se/javadoc/). Для других языков вы можете определить собственные соглашения. Комментирование классов, файлов и программ Классы, файлы и программы объединяет то, что все они включают много методов: файл или класс должен содержать набор родственных методов, программа содержит все ме- тоды. В каждом этом случае цель документирования в том, чтобы предоставить выразительную высокоуровневую ин- формацию о содержании файла, класса или программы. Общие принципы документирования классов Создайте перед каждым классом блочный комментарий, описывающий общие атрибуты класса. Учтите при этом следующее. Опишите подход к проектированию класса Обзорные комментарии, пре- доставляющие информацию, которую нельзя быстро извлечь из самого кода, осо- бенно полезны. Опишите философию проектирования класса, общий подход к его проектированию, альтернативные варианты проектирования, которые были рассмотрены и отброшены, и т. д. Опишите ограничения класса, предположения о его использовании и т. д. Как и в случае методов, убедитесь, что вы описали все ограничения, вы- текающие из проекта класса. Опишите также предположения о входных и выход- ных данных, аспекты ответственности за обработку ошибок, глобальные эффек- ты, источники алгоритмов и т. д. Прокомментируйте интерфейс класса Может ли другой программист ра- зобраться в использовании класса, не изучив его реализацию? Если нет, инкапсу- ляция класса подвергается серьезной опасности. Интерфейс класса должен содер- жать информацию, нужную для использования класса. Конвенция Javadoc требу- ет документирования хотя бы каждого параметра и каждого возвращаемого зна- чения (Sun Microsystems, 2000). Это надо сделать для каждого метода, предостав- ляемого каждым классом (Bloch, 2001). Не документируйте в интерфейсе класса детали реализации Главное пра- вило инкапсуляции гласит, что предоставлять информацию нужно только в со- ответствии с принципом необходимого знания: если у вас есть хоть какие-то со- мнения в том, предоставлять ли информацию, оставьте ее скрытой. Таким обра- зом, файл интерфейса класса должен содержать информацию, нужную для исполь- зования класса, но не для реализации или сопровождения класса. http://cc2e.com/3259 Перекрестная ссылка О формати- ровании классов, файлов и про- грамм см. раздел 31.8. Об исполь- зовании классов см. главу 6. ГЛАВА 32 Самодокументирующийся код 793 Общие принципы документирования файлов Создайте в начале файла блочный комментарий, описывающий содержание файла. Опишите назначение и содержание каждого файла В заголовочном ком- ментарии к файлу следует описать классы или методы, содержащиеся в файле. Если все методы программы находятся в одном файле, назначение файла очевидно: он содержит весь код программы. Если файл содержит один класс, назначение фай- ла также очевидно. Если же файл включает более одного класса, объясните, почему классы объеди- нены в одном файле. Если программа разделена на несколько файлов исходного кода не ради модуль- ности, а по иной причине, хорошее описание назначения файла окажется еще полезнее для программиста, которому придется изменять программу. Подумайте, поможет ли заголовочный комментарий к файлу определить, содержится ли в этом файле метод, выполняющий конкретное действие? Укажите в блочном комментарии свои имя/фамилию, адрес электронной почты и номер телефона При работе над крупными проектами большое зна- чение имеют такие факторы, как авторство и ответственность за конкретные фрагменты исходного кода. В небольших проектах (реализуемых с участием ме- нее 10 человек) годятся методики совместной разработки, при которых все чле- ны группы в равной степени отвечают за все разделы кода. Разработка более круп- ных систем требует, чтобы программисты специализировались на разных облас- тях кода, что делает совместное владение кодом нереальным. В этом случае сведения об авторстве нужно включать в листинг. Они позволят дру- гим программистам, работающим над кодом, узнать кое-что о стиле программи- рования и связаться с автором кода, если им понадобится помощь. В зависимости от того, над чем вы работаете (над отдельными методами, классами или програм- мами), сведения об авторстве следует включать на уровне методов, классов или про- грамм. Включите в файл тег версии Многие инструменты управления версиями встав- ляют сведения о версии в файл. Например, система CVS автоматически расширя- ет символы: // $Id$ в комментарий: // $Id: ClassName.java,v 1.1 2004/02/05 00:36:43 ismene Exp $ Это позволяет поддерживать актуальную информацию о версиях кода, не застав- ляя разработчиков прилагать никаких усилий, кроме вставки первоначального комментария $Id$. Включите в блочный комментарий юридическую информацию Многие компании любят включать в свои программы уведомления об авторских правах, конфиденциальности и другую юридическую информацию. Если вы работаете в такой компании, включите в код строку, похожую на указанную ниже. Узнайте у юриста своей компании, какую информацию включать в файлы, если это вообще следует делать. 794 ЧАСТЬ VII Мастерство программирования Пример уведомления об авторских правах (Java) // (c) Copyright 1993-2004 Steven C. McConnell. All Rights Reserved. Присвойте файлу имя, характеризующее его содержание Как правило, имя файла должно быть тесно связано с именем открытого класса, содержащегося в файле. Так, если класс называется Employee, файл следует назвать Employee.cpp. Некоторые языки, например Java, требуют, чтобы имя файла соответствовало имени класса. Книжная парадигма документирования программ Самые опытные программисты соглашаются с тем, что ме- тодики документирования, описанные в предыдущем раз- деле, полезны. Достоверных научных данных о полезности каждой из методик все еще мало, однако при объединении методик их эффективность не вызывает сомнений. В 1990 году Пол Оман и Кертис Кук опубликовали резуль- таты двух исследований «Книжной парадигмы (Book Para- digm)» документирования (Oman and Cook, 1990a, 1990b). Они искали стиль кодирования, который поддерживал бы несколько разных стилей чтения кода. Одной целью была поддержка нисходящего, восходящего и сфокусированно- го поиска. Другой целью было разделение кода на фрагменты, с которыми было бы легче работать, чем с длинным листингом однородного кода. Оман и Кук хо- тели, чтобы стиль предоставлял информацию и о высокоуровневой, и о низко- уровневой организации кода. Они обнаружили, что этих целей можно достичь, если рассматривать код как специфический вид книги и форматировать его соответствующим образом. Книж- ная парадигма предполагает, что код и документация организуются в несколько компонентов, похожих на компоненты книги и помогающих программистам получить высокоуровневое представление о программе. «Предисловие» — это группа вводных комментариев, таких как комментарии, обычно встречающиеся в начале файла. Они аналогичны предисловию книги и предоставляют программисту обзорную информацию о программе. «Содержание» определяет высокоуровневые файлы, классы и методы (главы), ко- торые могут быть указаны в форме списка, как главы обычной книги, или графи- чески — в виде структурной схемы. «Разделы» соответствуют отдельным частям методов, например, объявлениям ме- тодов, объявлениям данных и исполняемым операторам. «Перекрестные ссылки» — это карты перекрестных ссылок в коде, включающие номера строк. Низкоуровневые методики, опираясь на которые Оман и Кук воспользовались преимуществами сходств между книгой и листингом, похожи на методики, опи- санные в главе 31 и этой главе. Дополнительные сведения Это обсуждение основано на рабо- тах «The Book Paradigm for Improved Maintenance» (Oman and Cook, 1990a) и «Typographic Style Is More Than Cosmetic» (Oman and Cook, 1990b). Похо- жий подробный анализ см. в «Human Factors and Typography for More Readable Programs» (Baecker and Marcus, 1990). ГЛАВА 32 Самодокументирующийся код 795 Результат использования этих методик организации кода таков: когда Оман и Кук попросили группу опытных программистов выполнить одну задачу на сопровождение программы, среднее время выполнения этой задачи в случае программы из 1000 строк составило только около трех четвер- тей от времени, потребовавшегося для решения той же задачи при традицион- ной организации исходного кода (Oman and Cook, 1990b). Более того, при сопро- вождении кода, задокументированного в соответствии с Книжной парадигмой, про- граммисты получили в среднем на 20% более высокие оценки, чем при сопровож- дении кода, задокументированного традиционным образом. Оман и Кук пришли к выводу, что, обращая внимание на принципы структурирования книг, можно улуч- шить понятность кода на 10–20%. В исследовании, проведенном в Университете Торонто, были получены похожие результаты (Baecker and Marcus, 1990). Книжная парадигма подчеркивает важность создания документации, объясняю- щей и высокоуровневую, и низкоуровневую организацию программы. 32.6. Стандарты IEEE Ценными источниками сведений о документации, не относящейся к уровню ис- ходного кода, являются стандарты разработки ПО, принятые Институтом инже- неров по электротехнике и электронике (Institute for Electric and Electrical Engineers, IEEE). Стандарты IEEE разрабатываются группами профессионалов и ученых — экспертов в конкретной области. Каждый стандарт содержит резюме описывае- мой стандартом области и обычно включает обзор документации, уместной для данной области. В разработке стандартов принимают участие несколько национальных и между- народных организаций. Ведущая роль в определении стандартов разработки ПО принадлежит группе IEEE. Некоторые стандарты совместно приняты Международ- ной организацией по стандартизации (International Standards Organization, ISO), Альянсом электронной промышленности (Electronic Industries Alliance, EIA) и Меж- дународным инженерным консорциумом (International Engineering Consortium, IEC). Названия стандартов включают номер стандарта, год его принятия и само название. Так, «IEEE/EIA Std 12207-1997, информационные технологии — процессы жизнен- ного цикла ПО» — это стандарт номер 12207.2, принятый в 1997 году IEEE и EIA. Ниже я указал некоторые национальные и международные стандарты, в наиболь- шей степени относящиеся к проектам разработки ПО. Стандартом верхнего уровня является международный стан- дарт «ISO/IEC Std 12207, Information Technology — Software Life Cycle Processes», определяющий схему разработки про- граммных проектов и управления ими. В США этот стандарт был принят как «IEEE/ EIA Std 12207, Information Technology—Software Life Cycle Processes». Стандарты разработки ПО IEEE Std 830-1998 — рекомендуемая методика составления спецификаций требований к ПО http://cc2e.com/3266 http://cc2e.com/3273 796 ЧАСТЬ VII Мастерство программирования IEEE Std 1233-1998 — руководство по разработке спецификаций требований к си- стеме IEEE Std 1016-1998 — рекомендуемая методика описания проекта ПО IEEE Std 828-1998 — стандарт планов управления конфигурацией ПО IEEE Std 1063-2001 — стандарт пользовательской документации IEEE Std 1219-1998 — стандарт сопровождения ПО Стандарты контроля качества ПО IEEE Std 730-2002 — стандарт планирования контроля ка- чества ПО IEEE Std 1028-1997 — стандарт обзоров ПО IEEE Std 1008-1987 (R1993) — стандарт блочного тестирования ПО IEEE Std 829-1998 — стандарт документирования тестов ПО IEEE Std 1061-1998 — стандарт методологии метрик качества ПО Стандарты управления IEEE Std 1058-1998 — стандарт планов управления проек- тами разработки ПО IEEE Std 1074-1997 — стандарт разработки процессов жиз- ненного цикла ПО IEEE Std 1045-1992 — стандарт метрик продуктивности ПО IEEE Std 1062-1998 — рекомендуемая методика приобретения ПО IEEE Std 1540-2001 — стандарт процессов жизненного цикла ПО — управление риском IEEE Std 1490-1998 — руководство (заимствование стандарта PMI) к своду знаний по управлению проектами (PMBOK) Обзор стандартов Обзоры стандартов можно найти в двух источниках, указан- ных ниже. IEEE Software Engineering Standards Collection, 2003 Edition. New York, NY: Institute of Electrical and Electronics Engineers (IEEE). Этот всесторонний труд содержит 40 самых новых стандар- тов разработки ПО ANSI/IEEE на 2003 год. Каждый стандарт включает план документа, описание каждого компонента плана и обоснование этого компонента. Этот документ включает стандарты планов контроля качества, планов управления конфигурациями, документов тестирования, спецификаций требований, планов верификации и проверки, описаний проектирования, планов управления проектами и пользовательской документации. Данная книга представ- ляет собой квинтэссенцию опыта сотен лучших специалистов в своих областях и была бы выгодным приобретением практически при любой цене. Некоторые из стандартов доступны и отдельно. Все стандарты можно заказать у организа- http://cc2e.com/3280 http://cc2e.com/3287 http://cc2e.com/3294 http://cc2e.com/3201 ГЛАВА 32 Самодокументирующийся код 797 ции IEEE Computer Society из города Лос-Аламитос, шт. Калифорния, и на сайте www.computer.org/cspress. Moore, James W. Software Engineering Standards: A User’s Road Map. Los Alamitos, CA: IEEE Computer Society Press, 1997. Мур приводит обзор стандартов IEEE разработ- ки ПО. Дополнительные ресурсы Кроме стандартов IEEE, есть и другие источники информа- ции о документировании программ. Spinellis, Diomidis. Code Reading: The Open Source Perspective. Boston, MA: Addison-Wesley, 2003. Эта книга является праг- матичным исследованием методик чтения кода. В ней вы найдете советы по поиску нужного кода и чтению больших объемов кода, сведения об инструментах, облегчающих чте- ние кода, и массу полезных рекомендаций. SourceForge.net. Уже много лет обучению разработке ПО препятствует проблема поиска реальных примеров готового кода, которые можно было бы обсудить со студентами. Мно- гие люди быстрее всего учатся на реальных примерах, од- нако большинство реальных программ является собствен- ностью создавших их компаний. Благодаря Интернету и ПО с открытым исходным кодом эта ситуация улучшилась. Web- сайт Source Forge содержит код тысяч программ, написан- ных на C, C++, Java, Visual Basic, PHP, Perl, Python и других языках, причем весь этот код вы можете загрузить из сети совершенно бесплатно. Вы можете проанализи- ровать реальные примеры, гораздо более объемные, чем примеры, приведенные в этой книге. Для начинающих программистов, не имевших ранее дела с объем- ными примерами готового кода, этот Web-сайт окажется особенно полезен как источник и хороших, и плохих методик кодирования. Sun Microsystems. «How to Write Doc Comments for the Javadoc Tool», 2000. В этой статье ( http://java.sun.com/j2se/javadoc/ writingdoccomments/) описывается применение инструмента Javadoc для документирования программ Java. Она включает детальное описание разметки комментариев с использованием нотации стиля @tag, а также многие конкретные советы по написанию самих комментариев. Конвенции Javadoc яв- ляются, наверное, наиболее развитыми из нынешних стандартов документирования на уровне кода. Ниже указаны источники информации о других аспектах документирования ПО. McConnell, Steve. Software Project Survival Guide. Redmond, WA: Microsoft Press, 1998. В этой книге описывается документация, необходимая в критически важных про- ектах среднего размера. На Web-сайте книги вы можете найти много шаблонов документов. Интересно, сколько великих пи- сателей никогда не читали дру- гих авторов, сколько великих художников никогда не изуча- ли произведения других масте- ров, сколько высококвалифици- рованных хирургов никогда не учились, стоя за плечом колле- ги… И все же именно этого мы ожидаем от программистов. Дэйв Томас (Dave Thomas) http://cc2e.com/3208 http://cc2e.com/3215 http://cc2e.com/3222 798 ЧАСТЬ VII Мастерство программирования www.construx.com. Этот Web-сайт (Web-сайт моей компании) содержит многочисленные шаблоны документов, описания конвенций кодирования и другие ресурсы, связанные со всеми аспектами разработки ПО, включая документирование ПО. Post, Ed. «Real Programmers Don’t Use Pascal», Datamation, July 1983, pp. 263–265. В этой ироничной статье автор тоскует по «старым добрым временам» программирования на Фор- тране, когда программисты могли не волноваться о таких неприятных вопросах, как читабельность кода. Контрольный список: хорошие методики комментирования Общие аспекты Может ли программист, взглянувший на код, сразу понять его? Объясняют ли комментарии цель кода или резюмируют ли они выполняе- мые в коде действия вместо того, чтобы просто повторять код? Используете ли вы процесс программирования с псевдокодом для сокращения времени комментирования? Переписали ли вы хитрый код вместо того, чтобы комментировать его? Актуальны ли комментарии? Ясны ли комментарии? Корректны ли они? Позволяет ли стиль комментирования с легкостью изменять комментарии? Операторы и абзацы Избегаете ли вы комментариев в концах строк? Стремитесь ли вы отвечать в комментариях на вопрос «почему», а не «как»? Готовят ли комментарии читателя к последующему коду? Каждый ли комментарий важен? Были ли удалены или улучшены избыточ- ные, посторонние и неуместные комментарии? Документируете ли вы сюрпризы? Избегаете ли вы сокращений? Ясно ли различие между общими и детальными комментариями? Комментируете ли вы недокументированные возможности или код, предот- вращающий ошибки языка или среды? Объявления данных Указываете ли вы единицы измерения данных в местах объявления данных? Указываете ли вы диапазоны допустимых значений численных величин? Комментируете ли вы смысл закодированных значений? Комментируете ли вы ограничения входных данных? Документируете ли вы флаги до уровня отдельных битов? Комментируете ли вы каждую глобальную переменную в месте ее объявления? Поясняете ли вы при каждом использовании глобальной переменной ее глобальный характер при помощи конвенции именования, комментария или обоих способов? Заменили ли вы магические числа на именованные константы или перемен- ные, вместо того чтобы ограничиться простым документированием? http://cc2e.com/3229 http://cc2e.com/3236 http://cc2e.com/3243 |