Руководство по стилю программирования и конструированию по
 Скачать 7.6 Mb.
|
|
ГЛАВА 31 Форматирование и стиль 759 Абсолютно другой подход к удобочитаемости можно найти в следующей книге. Knuth, Donald E. Literate Programming. Cambridge University Press, 2001. В этой под- борке статей описывается концепция «грамотного программирования», объеди- няющего языки программирования и документирования. Кнут пишет о достоин- ствах грамотного программирования уже на протяжении 20 лет, но, хотя сам он может претендовать на титул Лучшего программиста планеты, грамотное програм- мирование никак не войдет в моду. Прочтите примеры его кода, чтобы сформи- ровать собственное мнение о причинах этой непопулярности. Ключевые моменты 쐽 Главная цель визуального форматирования — это подчеркивание логической структуры кода. В критерии оценки достижения этой цели входят аккуратность, единообразие, удобство чтения и сопровождения кода. 쐽 Критерий хорошего внешнего вида имеет вторичное, далеко не основное зна- чение. Однако если другие критерии соблюдены, а лежащий в основе код на- писан хорошо, то форматирование будет выглядеть привлекательно. 쐽 Visual Basic поддерживает явные блоки, а стандартное соглашение в Java пред- писывает их использование, поэтому, программируя на этих языках, вы може- те применять явные блоки. В C++ хорошо смотрится эмуляция явных блоков или обозначение границ блоков с помощью пар begin-end. 쐽 Структурирование кода само по себе имеет большое значение. Конкретные соглашения менее важны, чем сам факт, что вы последовательно применяете определенные соглашения. Договоренности по форматированию, соблюдае- мые лишь от случая к случаю, могут сильно ухудшить читаемость кода. 쐽 Многие аспекты форматирования сродни религиозным вопросам. Пытайтесь разделять объективные и субъективные предпочтения. Используйте явные кри- терии для обоснования вашей точки зрения при обсуждении стилевых пред- почтений. 760 ЧАСТЬ VII Мастерство программирования Г Л А В А 3 2 Самодокументирующийся код Содержание 쐽 32.1. Внешняя документация 쐽 32.2. Стиль программирования как вид документации 쐽 32.3. Комментировать или не комментировать? 쐽 32.4. Советы по эффективному комментированию 쐽 32.5. Методики комментирования 쐽 32.6. Стандарты IEEE Связанные темы 쐽 Форматирование: глава 31 쐽 Процесс программирования с псевдокодом: глава 9 쐽 Классы: глава 6 쐽 Высококачественные методы: глава 7 쐽 Программирование как общение: разделы 33.5 и 34.3 Если стандарты документации разумны, большинству про- граммистов нравится писать документацию. Как и форма- тирование, хорошая документация — свидетельство профес- сиональной гордости, выражаемой программистом в про- грамме. Документация имеет много вариантов, и после ее общего обзора в этой главе мы рассмотрим специфический вид документации, известный как «комментарии». 32.1. Внешняя документация Документация программного проекта складывается из ин- формации, содержащейся в листингах исходного кода, и внешней информации, которая обычно имеет форму отдель- ных документов или папок разработки блоков. В крупных http://cc2e.com/3245 Пишите код, исходя из того, что все программисты, которые бу- дут сопровождать вашу програм- му, — склонные к насилию пси- хопаты, знающие, где вы живете. Аноним Перекрестная ссылка У внешней документации имеются стандар- ты (см. раздел 32.6). ГЛАВА 32 Самодокументирующийся код 761 формальных проектах основная часть документации является внешней (Jones, 1998). Внешняя документация этапа конструирования обычно относится к более высокому уровню, чем код, и к более низкому, чем документация этапов опреде- ления проблемы, выработки требований и проектирования архитектуры. Папки разработки блоков Папка разработки блока (unit-development folder, UDF), или папка разработки ПО (software-development folder, SDF), — это неформальный документ, содержащий записи, используемые разработчи- ком во время конструирования. Термин «блок» здесь не имеет точного определения: обычно под ним понимается класс, а иногда — пакет или компонент. В первую очередь UDF служит для регистрации решений проектирования, которые нигде больше не документируются. Во многих проектах устанавливаются стандарты, определяющие минимальное содержание UDF — например, копии релевантных требований, высокоуровневые аспекты проектирования, реализуемые в блоке, копии стандартов разработки, листинги кода и заметки разработчика блока. Иногда заказчик требует, чтобы ему предоставлялись папки UDF; часто они предназна- чены только для внутреннего использования. Документ детального проектирования Документ детального проектирова- ния описывает низкоуровневую конструкцию. Он очерчивает решения, принятые при проектировании классов или методов, рассмотренные варианты и мотивы вы- бора окончательных подходов. Иногда эта информация включается в формаль- ный документ; при этом детальное проектирование обычно рассматривается как этап, отдельный от конструирования. Иногда этот документ состоит преимуще- ственно из заметок разработчиков, собранных в UDF, но чаще эта документация присутствует только в самом коде. 32.2. Стиль программирования как вид документации В отличие от внешней внутренняя документация включается в сам код. Это наи- более подробный вид документации, относящийся к уровню команд исходного кода. Внутренняя документация сильнее всего связана с кодом, поэтому при из- менении кода она чаще остается корректной, чем документация иных видов. Главный вклад в документацию уровня кода вносится не комментариями, а хоро- шим стилем программирования. Грамотное структурирование программы, исполь- зование простых и понятных подходов, удачный выбор имен переменных и ме- тодов, использование именованных констант вместо литералов, ясное формати- рование, минимизация сложности потока управления и структур данных — все это аспекты стиля программирования. Вот пример плохого стиля программирования: Дополнительные сведения О пап- ках разработки блоков см. в «The Unit Development Folder (UDF): An Effective Management Tool for Soft- ware Development» (Ingrassia, 1976) и «The Unit Development Fol- der (UDF): A Ten-Year Perspective» (Ingrassia, 1987). 762 ЧАСТЬ VII Мастерство программирования Пример плохого документирования кода из-за плохого стиля программирования (Java) for ( i = 2; i <= num; i++ ) { meetsCriteria[ i ] = true; } for ( i = 2; i <= num / 2; i++ ) { j = i + i; while ( j <= num ) { meetsCriteria[ j ] = false; j = j + i; } } for ( i = 1; i <= num; i++ ) { if ( meetsCriteria[ i ] ) { System.out.println ( i + “ meets criteria.” ); } } Что, по-вашему, делает этот метод? Его непонятность не имеет никакого обоснования. Он плохо документирован, но дело не в отсутствии комментариев, а в плохом стиле про- граммирования. Имена переменных неинформативны, а способ форматирования груб. Вот улучшенный вариант того же кода — простое улучшение стиля программирования делает его смысл гораздо яснее: Пример документирования кода без использования комментариев — за счет хорошего стиля (Java) for ( primeCandidate = 2; primeCandidate <= num; primeCandidate++ ) { isPrime[ primeCandidate ] = true; } for ( int factor = 2; factor < ( num / 2 ); factor++ ) { int factorableNumber = factor + factor; while ( factorableNumber <= num ) { isPrime[ factorableNumber ] = false; factorableNumber = factorableNumber + factor; } } for ( primeCandidate = 1; primeCandidate <= num; primeCandidate++ ) { if ( isPrime[ primeCandidate ] ) { System.out.println( primeCandidate + “ is prime.” ); } } Одного взгляда на этот код достаточно, чтобы понять, что он имеет какое-то от- ношение к простым числам (prime numbers). Второй взгляд показывает, что он Перекрестная ссылка Здесь пе- ременная factorableNumber ис- пользуется исключительно ради пояснения операции. О добав- лении переменных с целью по- яснения операций см. подраз- дел «Упрощение сложных выра- жений» раздела 19.1. ГЛАВА 32 Самодокументирующийся код 763 находит простые числа от 1 до Num. Что касается первого фрагмента, то, взгля- нув на него пару раз, вы даже не поймете, где завершаются циклы. Различие между двумя фрагментами с комментариями не связано — их вообще нет. Однако второй фрагмент читать гораздо лучше, приближаясь к Святому Гра- алю понятности — самодокументированию. Задача документирования такого кода во многом решается за счет хорошего стиля программирования. Если код напи- сан хорошо, комментарии — всего лишь глазурь на пирожном читабельности. Контрольный список: самодокументирующийся код Классы Формирует ли интерфейс класса согласованную абстракцию? Удачное ли имя присвоено классу? Описывает ли оно главную цель класса? Ясно ли интерфейс описывает применение класса? Достаточно ли абстрактен интерфейс класса, чтобы можно было не думать о том, как реализованы его сервисы? Можете ли вы рассматривать класс как «черный ящик»? Методы Точно ли имя каждого метода описывает выполняемые в нем действия? Выполняет ли каждый метод одну и только одну хорошо определенную задачу? Все ли части метода, которые целесообразно поместить в отдельные мето- ды, сделаны отдельными методами? Очевиден ли и ясен ли интерфейс каждого метода? Имена данных Достаточно ли описательны имена типов, чтобы помогать документировать объявления данных? Удачно ли названы переменные? Переменные используются только с той целью, в соответствии с которой они названы? Присвоены ли счетчикам циклов более информативные имена, чем i, j и k? Используете ли вы грамотно названные перечисления вместо самодельных флагов или булевых переменных? Используете ли вы именованные константы вместо магических чисел или магических строк? Проводят ли конвенции именования различия между именами типов, пере- числений, именованных констант, локальных переменных, переменных класса и глобальных переменных? Организация данных Используете ли вы дополнительные переменные для пояснения кода? Сгруппированы ли обращения к переменным? Просты ли типы данных? Способствуют ли они минимизации сложности? Обращаетесь ли вы к сложным данным при помощи абстрактных методов доступа (абстрактных типов данных)? http://cc2e.com/3252 764 ЧАСТЬ VII Мастерство программирования Управление Очевиден ли номинальный путь выполнения кода? Сгруппированы ли связанные операторы? Вынесены ли относительно независимые группы операторов в отдельные методы? Следует ли нормальный вариант после if, а не после else? Просты ли управляющие структуры? Способствуют ли они минимизации сложности? Выполняет ли цикл одну и только одну функцию, как это делает хорошо спроектированный метод? Минимизировали ли вы вложенность? Упростили ли вы булевы выражения путем использования дополнительных булевых переменных, булевых функций и таблиц принятия решений? Форматирование Характеризует ли форматирование программы ее логическую структуру? Проектирование Прост ли код? Избегаете ли вы «хитрых» решений? Скрыты ли детали реализации настолько, насколько возможно? Стараетесь ли вы писать программу в терминах проблемной области, а не структур вычислительной техники или языка программирования? 32.3. Комментировать или не комментировать? Комментарии легче написать плохо, а не хорошо, и комментирование иногда бывает скорее вредным, чем полезным. Жаркие дискуссии по поводу достоинств комментирования часто напоминают философские дебаты о моральных досто- инствах, и это наводит меня на мысль о том, что, будь Сократ программистом, между ним и его учениками могла бы произойти следующая беседа. Комменто Действующие лица: ФРАСИМАХ Неопытный пурист теории, который верит всему, что читает. КАЛЛИКЛ Закаленный в боях представитель старой школы — «настоящий» программист. ГЛАВКОН Молодой, самоуверенный, энергичный программист. ИСМЕНА Опытная разработчица, уставшая от громких обещаний и просто желающая найти несколько работающих методик. СОКРАТ Мудрый опытный программист. Мизансцена: Завершение ежедневного собрания группы — Желает ли кто-то обсудить еще что-нибудь, прежде чем мы вернемся к работе? — спрашивает Сократ. — Я хочу предложить стандарт комментирования для наших проектов, — гово- рит Фрасимах. — Некоторые наши программисты почти не комментируют свой код, а всем известно, что код без комментариев нечитаем. ГЛАВА 32 Самодокументирующийся код 765 — Ты, должно быть, еще менее опытен, чем я думал, — отвечает Калликл. — Ком- ментарии — это академическая панацея, и любому, кто писал реальные програм- мы, известно, что комментарии затрудняют чтение кода, а не облегчают. Естествен- ный язык менее точен, чем Java или Visual Basic, и страдает от избыточности, тог- да как операторы языков программирования лаконичны и попадают в самое яб- лочко. Если кто-то не может написать ясный код, разве ему удастся написать яс- ные комментарии? Кроме того, комментарии устаревают при изменениях кода. Доверяя устаревшим комментариям, ты сам себе роешь яму. — Полностью согласен, — вступает в разговор Главкон. — Щедро прокомментиро- ванный код читать труднее, потому что в этом случае читать приходится больше. Мало того, что я должен читать код, так мне нужно читать еще и кучу комментариев! — Подождите минутку, — вставляет свои две драхмы Исмена, ставя чашку кофе. — Конечно, злоупотребление комментариями возможно, но хорошие комментарии ценятся на вес золота. Мне приходилось сопровождать код как с комментариями, так и без них, и, будь у меня выбор, я бы предпочла первый вариант. Не думаю, что нам нужен стандарт, заставляющий писать один комментарий на каждые x строк кода, но побудить всех программистов комментировать код не помешает. — Если комментарии — пустая трата времени, почему все их используют, Калликл? — спрашивает Сократ. — Или потому, что таково требование, или потому, что человек прочитал где-то о пользе комментариев. Ни один программист, когда-либо задумавшийся об этом, не пришел к выводу, что комментарии полезны. — Исмена считает, что они полезны. Она уже три года сопровождает твой код без комментариев и чужой код с комментариями. Ее мнение ты уже слышал. Что ты скажешь на это? — Комментарии бесполезны, потому что они просто повторяют код в более мно- гословной… — Подожди, — прерывает Калликла Фрасимах. — Хорошие комментарии не повторяют код и не объясняют его. Они поясняют его цель. Коммен- тарии должны объяснять намерения программиста на более высоком уровне абстракции, чем код. — Верно, — соглашается Исмена. — Если я ищу фрагмент, который мне нужно из- менить или исправить, я просматриваю комментарии. Комментарии, повторяю- щие код, на самом деле бесполезны, потому что все уже сказано в самом коде. Когда я читаю комментарии, я хочу, чтобы они напоминали оглавление книги. Коммен- тарии должны помочь мне найти нужный раздел, а после этого я начну читать код. Гораздо быстрее прочитать одно предложение на обычном языке, чем ана- лизировать 20 строк кода на языке программирования. Исмена наливает себе вторую чашку кофе. — Мне кажется, что люди, отказывающиеся писать комментарии, (1) думают, что их код понятнее, чем мог бы быть, (2) считают, что другие программисты гораз- до сильнее интересуются их кодом, чем есть на самом деле, (3) думают, что дру- гие программисты умнее, чем есть на самом деле, (4) ленятся или (5) боятся, что кто-то другой узнает, как работает их код. 766 ЧАСТЬ VII Мастерство программирования — В этом смысле очень помогли бы обзоры кода, Сократ, — продолжает Исмена. — Если кто-то утверждает, что комментарии писать не нужно, и получает во вре- мя обзора кучу вопросов — если сразу несколько коллег спрашивают его: „Что про- исходит в этом фрагменте твоего кода?“ — он начинает писать комментарии. Если программист не дойдет до этого сам, его руководитель сможет заставить его пи- сать комментарии. — Я не утверждаю, Калликл, что ты ленишься или боишься, что кто-то другой пой- мет твой код. Я работала с твоим кодом и могу сказать, что ты — один из лучших программистов компании. Но будь чуточку добрее, а? Мне было бы легче сопро- вождать твой код, если бы ты писал комментарии. — Но это пустая трата времени, — не сдается Калликл. — Код хорошего програм- миста должен быть самодокументирующимся: все, что нужно знать другим про- граммистам, должно быть в самом коде. — Нет! — Фрасимах вскакивает со стула. — В коде и так уже есть все, что нужно знать компилятору! С таким же успехом можно было бы сказать, что все, что нуж- но знать другим программистам, уже есть в двоичном исполняемом файле! Если бы мы только были достаточно умны, чтобы уметь читать его! Информации о том, что программист собирался сделать, в коде нет. Фрасимах замечает, что вскочил с места, и садится. — Сократ, это немыслимо. Почему мы спорим о важности комментариев? Во всех книгах, которые я читал, говорится, что комментарии полезны и что на них не сто- ит экономить. Мы зря теряем время. — Успокойся, Фрасимах. Спроси у Калликла, как давно он программирует. — Действительно, как давно, Калликл? — Ну, я начал с системы Акрополь IV где-то 15 лет назад. Думаю, что я стал свидетелем рождения и гибели пример- но десятка крупных приложений. А еще в десятке проектов я работал над крупными компонентами. Две из этих систем включали более полумиллиона строк кода, так что я знаю, о чем говорю. Комментарии совершенно бесполезны. Сократ бросает взгляд на более молодого программиста. — Как говорит Калликл, с комментариями действительно связано много проблем, и ты не поймешь это, пока не приобретешь больше опыта. Если комментировать код неграмотно, комментарии не просто бесполезны — они вредны. — Они бесполезны, даже если комментировать код грамотно, — заявляет Калликл. — Комментарии менее точны, чем язык программирования. Лично я думаю, что лучше вообще их не писать. — Постой, — говорит Сократ. — Исмена согласна с тем, что комментарии менее точны, но она утверждает, что комментарии поднимают программиста на более высокий уровень абстракции, а все мы знаем, что абстракция — один из самых эффективных инструментов, имеющихся в нашем распоряжении. — Я с этим не согласен, — заявляет Главкон. — Нам следует концентрироваться не на комментариях, а на читабельности кода. При рефакторинге большинство Ясно, что на некотором уровне комментарии должны быть по- лезны. Думать иначе означало бы полагать, что понятность программы не зависит от того, сколько информации о ней уже известно читающему програм- му человеку. Б. Шейл (B. A. Sheil) |