Руководство по стилю программирования и конструированию по
 Скачать 7.6 Mb.
|
|
ГЛАВА 30 Инструменты программирования 711 Часть VII МАСТЕРСТВО ПРОГРАММИРОВАНИЯ Глава 31. Форматирование и стиль Глава 32. Самодокументирующийся код Глава 33. Личность Глава 34. Основы мастерства Глава 35. Где искать дополнительную информацию 712 ЧАСТЬ VII Мастерство программирования Г Л А В А 3 1 Форматирование и стиль Содержание 쐽 31.1. Основные принципы форматирования 쐽 31.2. Способы форматирования 쐽 31.3. Стили форматирования 쐽 31.4. Форматирование управляющих структур 쐽 31.5. Форматирование отдельных операторов 쐽 31.6. Форматирование комментариев 쐽 31.7. Форматирование методов 쐽 31.8. Форматирование классов Связанные темы 쐽 Самодокументируемый код: глава 32 쐽 Инструменты для форматирования кода: «Редактирование» в разделе 30.2 В этой главе рассматривается эстетический аспект программирования — форма- тирование исходного кода программы. Зрительное и интеллектуальное наслаж- дение, получаемое от хорошо отформатированного кода, — удовольствие, кото- рое способны оценить лишь немногие непрограммисты. Но программисты, гор- дящиеся своей работой, получают огромное эстетическое удовлетворение от про- цесса шлифовки визуальной структуры кода. Методики, описанные в этой главе, не влияют на скорость выполнения, объем памяти и другие внешние аспекты программы. Но от них зависит, насколько лег- ко вы сможете понять, пересмотреть и исправить этот код спустя несколько ме- сяцев после его создания. От них также зависит, насколько легко другие смогут его прочесть, понять и изменить в ваше отсутствие. Эта глава полна мелких подробностей, которые обычно имеют в виду, говоря о «внимании к деталям». В течение жизни проекта внимание к таким деталям влия- ет на качество и итоговое удобство сопровождения создаваемого кода. Они слиш- ком интегрированы в процесс кодирования, чтобы их можно было эффективно изменить потом. Если вы вообще собираетесь их учитывать, учтите их при пер- http://cc2e.com/3187 ГЛАВА 31 Форматирование и стиль 713 воначальном конструировании. Перед началом работы над групповым проектом, дайте своей команде прочитать эту главу и согласуйте общий стиль кодирования. Вы можете согласиться не со всем, что здесь прочтете, но я стремился не столько добиться полного одобрения моего мнения, сколько убедить вас рассмотреть вопросы, связанные со стилем форматирования. Если вы гипертоник, переходи- те к следующей главе — она вызовет меньше споров. 31.1. Основные принципы форматирования В этом разделе мы обсудим теорию хорошего форматирования. Остальная часть главы посвящена практике. Экстремальные случаи форматирования Посмотрите на метод, приведенный в листинге 31-1: Листинг 31-1. Пример № 1 форматирования кода (Java) /* Используем способ сортировки методом вставок для сортировки массива «data» в возрастающем порядке. Этот метод предполагает, что [ firstElement ] не является первым элементом данных и элемент data[ firstElement-1 ] достижим. */ public void InsertionSort( int[] data, int firstElement, int lastElement ) { /* Заменяем элемент, расположенный на нижней границе интервала, элементом, который гаранти- рованно будет первым в сортированном списке. */ int lowerBoundary = data [ firstElement-1 ]; data[ firstElement-1 ] = SORT_MIN; /* Элементы в позициях от firstElement до sortBoundary-1 всегда сортированы. При каждом проходе цикла sort- Boundary увеличивается, и элемент, соответствующий новому sortBoundary, возможно, будет неправильно отсортирован, поэтому он вставляется в надлежащую позицию массива где-то между firstElement и sortBoundary. */ for ( int sortBoundary = firstElement+1; sortBoundary <= lastElement; sortBoundary++ ) { int insertVal = data[ sortBoundary ]; int insertPos = sortBoundary; while ( insertVal < data[ insertPos-1 ] ) { data[ insertPos ] = data[ insertPos-1 ]; insertPos = insertPos-1; } data[ insertPos ] = insertVal; } /* Возвращаем исходное значение элементу, расположенному на нижней границе интервала */ data[ firstElement-1 ] = lowerBoundary; } Этот метод синтаксически корректен. Он прокомментирован и содержит хоро- шие имена переменных и понятную логику. Если не верите, прочтите его и най- дите ошибку! Чего не хватает этому методу, так это хорошего форматирования. Это крайний случай, стремящийся к «минус бесконечности» на шкале способов форматирования с диапазоном от плохих до хороших. Листинг 31-2 показывает менее экстремальный вариант: Листинг 31-2. Пример № 2 форматирования кода (Java) /* Используем способ сортировки методом вставок для сортировки массива «data» в возрастающем порядке. Этот метод предполагает, что [ firstElement ] не является первым элементом данных и элемент data[ firstElement-1 ] достижим. */ public void InsertionSort( int[] data, int firstElement, int lastElement ) { /* Заменяем элемент, расположенный на нижней границе интервала, элементом, 714 ЧАСТЬ VII Мастерство программирования который гарантированно будет первым в сортированном списке. */ int lowerBoundary = data[ firstElement-1 ]; data[ firstElement-1 ] = SORT_MIN; /* Элементы в позициях от firstElement до sortBoundary-1 всегда отсортированы. При каждом проходе цикла sortBoundary увеличивается, и элемент, соответствующий новому каждом проходе цикла sortBoundary увеличивается, и элемент, соответствующий новому sortBoundary, возможно, будет неправильно отсортирован, поэтому он вставляется в надлежащую позицию массива между firstElement и sortBoundary. */ for ( int sortBoundary = firstElement+1; sortBoundary <= lastElement; sortBoundary++ ) { int insertVal = data[ sortBoundary ]; int insertPos = sortBoundary; while ( insertVal < data[ insertPos-1 ] ) { data[ insertPos ] = data[ insertPos-1 ]; insertPos = insertPos-1; } data[ insertPos ] = insertVal; } /* Возвращаем исходное значение элементу, расположенному на нижней границе интервала */ data[ firstElement-1 ] = lowerBoundary; } Это тот же код, что и в листинге 31-1. Хотя большинство согласится, что такое форматирование кода гораздо лучше первого примера, но код все еще не слиш- ком читабелен. Текст еще расположен слишком кучно и не содержит подсказок о логической организации метода. Такое форматирование соответствует 0 на шкале вариантов форматирования. Первый пример был несколько надуман, но второй не так уж редко встречается в жизни. Я видел программы, состоящие из нескольких тысяч строк кода, форматированные столь же плохо, как и здесь. А при отсутствии документации и плохих именах переменных общая читабельность была еще хуже, чем в этом примере. Этот код отформатирован для компьютера, и нет никаких свидетельств, что автор думал о людях, которые будут читать его код. Листинг 31-3 содержит усовершенствованный вариант. Листинг 31-3. Пример № 3 форматирования кода (Java) /* Используем способ сортировки методом вставок для сортировки массива «data» в возрастающем порядке. Этот метод предполагает, что [ firstElement ] не является первым элементом данных и элемент data[ firstElement-1 ] достижим. */ public void InsertionSort( int[] data, int firstElement, int lastElement ) { // Заменяем элемент, расположенный на нижней границе интервала, элементом, // который гарантированно будет первым в отсортированном списке. int lowerBoundary = data[ firstElement-1 ]; data[ firstElement-1 ] = SORT_MIN; ГЛАВА 31 Форматирование и стиль 715 /* Элементы в позициях от firstElement до sortBoundary-1 всегда отсортированы. При каждом проходе цикла sortBoundary увеличивается, и элемент, соответствующий новому sortBoundary, возможно, будет неправильно отсортирован, поэтому он вставляется в надлежащую позицию массива где-то между firstElement и sortBoundary. */ for ( int sortBoundary = firstElement + 1; sortBoundary <= lastElement; sortBoundary++ ) { int insertVal = data[ sortBoundary ]; int insertPos = sortBoundary; while ( insertVal < data[ insertPos - 1 ] ) { data[ insertPos ] = data[ insertPos - 1 ]; insertPos = insertPos - 1; } data[ insertPos ] = insertVal; } // Возвращаем исходное значение элементу, // расположенному на нижней границе интервала data[ firstElement - 1 ] = lowerBoundary; } Это форматирование соответствует строго положительному значению на шкале вариантов форматирования с диапазоном от плохих до хороших. Теперь этот метод организован в соответствии с принципами, объясняемыми на протяжении всей этой главы. Метод гораздо удобнее читать, а усилия, приложенные к документи- рованию и выбору хороших имен переменных, теперь очевидны. Имена перемен- ных и в прошлых примерах были столь же хороши, однако форматирование было настолько плохим, что от них не было пользы. Единственное различие между этим и первыми двумя примерами заключается в использовании пробелов и разделителей — код и комментарии абсолютно оди- наковы. Пробелы нужны исключительно людям — ваш компьютер смог бы про- честь все три фрагмента одинаково легко. Не расстраивайтесь, если не можете сделать это не хуже вашего компьютера! Основная теорема форматирования Основная теорема форматирования гласит, что хорошее визуальное форматиро- вание показывает логическую структуру программы. Создание красивого кода — хорошо, а демонстрация структуры кода — лучше. Если одна методика лучше показывает структуру кода, а другая выглядит красивей, используйте ту, которая лучше демонстрирует струк- туру. Эта глава содержит массу примеров стилей форматирования, выглядящих хорошо, но искажающих логическую организацию кода. Отдавая на практике предпочтение логическому представлению, обычно нельзя получить уродливый код, если только сама логика этого кода не уродлива. Методики, позволяющие хорошему коду выглядеть хорошо, а плохому — плохо, полезней, чем методики, позволяющие любому коду выглядеть хорошо. 716 ЧАСТЬ VII Мастерство программирования Интерпретация программы человеком и компьютером Форматирование — это ключ к структуре программы. Ком- пьютеру важна исключительно информация о скобках или операторах begin и end, а читатель-человек склонен делать выводы из визуального представления кода. Взгляните на фрагмент кода, приведенный в листинге 31-4, схема отсту- пов в котором заставляет человека думать, что все три вы- ражения выполняются при каждом проходе цикла. Листинг 31-4. Пример форматирования, рассказывающего разные истории человеку и компьютеру (Java) // меняем местами правые и левые элементы во всем массиве for ( i = 0; i < MAX_ELEMENTS; i++ ) leftElement = left[ i ]; left[ i ] = right[ i ]; right[ i ] = leftElement; Если код не содержит обрамляющих скобок, компилятор будет выполнять пер- вое выражение MAX_ELEMENTS раз, а второе и третье — по одному разу. Отступы делают очевидным и для вас, и для меня, что автор кода хотел выполнять все три выражения и собирался поместить скобки вокруг них. Компилятору это неоче- видно. Листинг 31-5 содержит другой пример: Листинг 31-5. Другой пример форматирования, рассказывающего разные истории человеку и компьютеру (Java) x = 3+4 * 2+7; Человек, читающий этот код, будет склонен интерпретировать это выражение так, что переменной x присваивается значение (3+4) * (2+7), т. е. 63. Компьютер про- игнорирует пробелы и подчинится правилам приоритета, интерпретируя это выражение, как 3 + (4*2) + 7 или 18. Идея в том, что хорошая схема форматиро- вания приведет в соответствие визуальную и логическую структуру программы, т. е. расскажет одну и ту же историю и человеку, и компьютеру. Насколько важно хорошее форматирование? Знание схем программирования и правил изложения программы может суще- ственно повлиять на возможность осмысления программы. В книге «[The] Elements of [Programming] Style» Керниган и Плоджер (Kernighan and Plauger) также определяют то, что мы назвали правилами изложения. Наши эмпи- рические результаты подтверждают эти правила: необходимость написа- ния программ в определенном стиле вызвана не только эстетическими сооб- ражениями. Создание программ в определенной манере имеет скорее психо- логическую подоплеку: программисты возлагают большие надежды на то, что другие разработчики будут следовать их правилам изложения. Если эти пра- вила нарушаются, то вся польза, на которую надеется программист, сводится к нулю. Эти выводы подтверждаются результатами экспериментов с начи- Любой дурак может написать код, понятный компьютеру. Хо- рошие программисты пишут код, понятный людям. Мартин Фаулер (Martin Fowler) ГЛАВА 31 Форматирование и стиль 717 нающими и подготовленными студентами-программистами, а также с опыт- ными разработчиками, упоминаемыми в этой статье. —Эллиот Соловей и Кейт Эрлих (Elliot Soloway and Kate Ehrlich) В вопросах форматирования, возможно, сильнее, чем в дру- гих аспектах программирования, проявляется разница между взаимодействием с компьютером и взаимодействием с чело- веком. Меньшая задача программирования состоит в напи- сании программы в понятном для компьютера виде, б ó льшая — в том, чтобы написать ее так, чтобы другие люди могли ее прочесть. В классической статье «Perception in Chess» Чейз и Саймон (Chase and Simon) со- общили об исследовании, в котором сравнивались способности экспертов и но- вичков запоминать позиции фигур в шахматах (1973). Когда фигуры были рас- ставлены так, как это могло сложиться во время игры, память экспертов во много раз превосходила способности начинающих. Когда же фигуры были расставле- ны случайно, то результаты экспертов и новичков отличались не намного. Тради- ционно этот результат объясняется тем, что память эксперта несущественно от- личается от памяти начинающих, но эксперты используют систему знаний, по- могающую им запоминать определенные виды информации. Если новые данные соответствуют этой системе знаний (в данном случае осмысленному размещению шахматных фигур), эксперты легко могут их запомнить. Если же новая информа- ция в эту систему не укладывается (шахматные фигуры расположены в случай- ном порядке) эксперт может запомнить ее ничуть не лучше новичка. Несколько лет спустя Бен Шнейдерман (Ben Shneiderman) повторил результаты Чейза и Саймона в сфере компьютерного программирования и сообщил о них в статье «Exploratory Experiments in Programmer Behavior» (1976). Шнейдерман вы- яснил, что если программные операторы расположены в осмысленном порядке, то эксперты могли запомнить их лучше, чем новички. Когда же операторы пере- мешивались, преимущество экспертов снижалось. Результаты Шнейдермана были подтверждены и в других исследованиях (McKeithen et al., 1981; Soloway and Ehrlich, 1984). Основная концепция подтверждалась в играх го и бридже, а также в элек- тронике, музыке и физике (McKeithen et al., 1981). После публикации первого издания этой книги Хенк — один из программистов, рецензировавших рукопись, — сказал: «Я удивился, что ты недостаточно активно ратовал за использование такого стиля скобок: for ( ...) { } Странно, что ты вообще упомянул такой стиль скобок, как этот: for ( ...) { } Я думал, что, поскольку и я, и Тони приводили доводы в пользу первого стиля, ты предпочтешь его». Перекрестная ссылка Хорошее форматирование — один из ключей к удобочитаемости (см. раздел 34.3). 718 ЧАСТЬ VII Мастерство программирования Я ответил: «Ты, наверное, имел в виду, что ты ратовал за применение первого сти- ля, а Тони — второго, не так ли? Тони приводил доводы в пользу второго стиля, а не первого». Хенк ответил: «Забавно. В последнем проекте, над которым Тони и я работали вместе, я предпочитал использовать стиль №2, а Тони — №1. Весь проект мы спо- рили о том, какой стиль лучше. Полагаю, мы уговорили друг друга предпочесть противоположный стиль!» Этот случай, а также исследования, процитированные выше, позволяют предположить, что структура помогает экспертам воспринимать, осмыс- ливать и запоминать важные свойства программ. Опытные программис- ты часто упорно цепляются за собственный стиль, даже если он очень сильно отличается от стиля, применяемого другими экспертами. Но практический результат показывает, что детали конкретного способа структурирования программы гораздо менее важны, чем сам факт единообразного структурирования программы. Форматирование как религия Важное влияние, которое привычный способ структурирования среды оказывает на процесс понимания и запоминания, заставило исследователей выдвинуть та- кую гипотезу: если форматирование отличается от схемы, используемой экспер- тами, оно может повредить их способности читать программу (Sheil, 1981; Soloway and Ehrlich, 1984). Такая возможность вкупе с не только логическим, но и эстети- ческим значением форматирования привела к тому, что дебаты вокруг формати- рования программ часто больше похожи на религиозные войны, а не на фило- софские диспуты. Грубо говоря, очевидно, что некоторые виды форматиро- вания лучше других. Последовательное улучшение фрагмен- тов одного и того же кода, показанное в начале этой главы, делает это утверждение бесспорным. В этой книге я не буду избегать деликатных вопросов о форматировании только потому, что они спорны. Хорошие программисты должны непредвзято относиться к привычным для них способам форматирования и признавать другие варианты, доказавшие свое преимущество по отношению к использовавшимся ранее, даже если при переходе к новым ме- тодам возникнет некоторый начальный дискомфорт. Перекрестная ссылка Если вы смешиваете вопросы разработ- ки ПО и религии, прочтите раз- дел 34.9, прежде чем продол- жить чтение остальной части этой главы. ГЛАВА 31 Форматирование и стиль 719 Цели хорошего форматирования Многие решения о том, как должно выглядеть хорошее фор- матирование, представляют собой субъективные эстетичес- кие оценки; часто можно достичь одной и той же цели по- разному. Вы можете сделать споры о субъективных вопро- сах менее субъективными, если явно укажете критерии ва- ших предпочтений. Говоря объективно, хорошая схема фор- матирования должна делать следующие вещи. Точно представлять логическую структуру кода Сно- ва повторим Основную теорему форматирования: главная цель хорошего форматирования — показать логическую структуру кода. Для демонстрации логической структуры программисты обычно применяют отступы и другие не- отображаемые символы. Единообразно показывать логическую структуру кода Некоторые стили форматирования состоят из правил с таким количеством исключений, что по- следовательно их соблюдать практически невозможно. Действительно хороший стиль подходит в большинстве случаев. Улучшать читабельность Стратегия использования отступов, соответствую- щая логике, но усложняющая процесс чтения кода, бесполезна. Схема формати- рования, использующая пробелы и разделители только там, где они требуются ком- пилятору, логична, но читать такой код невозможно. Хорошая структура форма- тирования упрощает чтение кода. Выдерживать процедуру исправления Лучшие схемы форматирования хо- рошо переносят модификацию кода. Исправление одной строки не должно при- водить к изменению нескольких других. В дополнение к этим критериям иногда во внимание принимается и задача ми- нимизации количества строк кода, необходимых для реализации простого выра- жения или блока. Как воспользоваться принципами хорошего форматирования на практике Критерии хорошей схемы форматирования могут служить основой для обсуждения возможных вариантов форматов, помогая отличить субъек- тивные причины в предпочтении одного стиля форматирования перед другим Оценка критерия с нескольких точек зрения может привести к разным выводам. Так, если вы твердо убеждены, что минимизация количества строк кода очень важна (вероятно, потому, что у вас маленький монитор), вы можете критиковать один стиль только за то, что для списка параметров метода он использует на две стро- ки больше, чем какой-то другой. Эксперименты выявили хруп- кость программистской квали- фикации: опытные программис- ты имеют стойкие представления о том, как должны выглядеть программы, и, если эти убежде- ния нарушаются — казалось бы, даже безобидными способами, — их производительность ради- кально ухудшается. Эллиот Соловей и Кейт Эрлих (Elliot Soloway and Kate Ehrlich) 720 ЧАСТЬ VII Мастерство программирования 31.2. Способы форматирования Вы можете получить хороший формат кода, по-разному используя несколько инструментов для форматирования. Неотображаемые символы Используйтенеотображаемыесимволыдляулучшениячитаемости. Неотображаемые символы, к которым относятся пробелы, знаки табуляции, переводы строк и пус- тые строки, — это основное средство для демонстрации структуры программы. Вам вряд ли придет в голову писать книгу без пробелов между словами, разбиения на абзацы и деления на главы. Может, такую книгу и можно прочитать от начала до конца, но прак- тически невозможно просматривать ее в поисках какой-то мысли или важного эпизода. Еще хуже, что такой формат книги не позволит показать читателю, как автор намеревал- ся организовать информацию. Структура, предлагаемая ав- тором, дает подсказку о логической организации темы. Разбиение книги на главы, абзацы и предложения показывает читателю, как сле- дует мысленно организовывать тему. Если эта организация неочевидна, читате- лю приходится самому ее домысливать, что налагает на него более тяжкое бремя и увеличивает вероятность никогда не узнать, как на самом деле организована данная тема. Информация, содержащаяся в программе, сосредоточена еще плотней, чем инфор- мация в большинстве книг. Если страницу книги можно прочесть и понять за 1 или 2 минуты, то большинство программистов не могут читать и понимать лис- тинг программы со скоростью, даже приблизительно сравнимой с этой. Программа должна давать гораздо больше подсказок о своей организации, чем книга. Группировка Еще один способ применения неотображаемых символов — груп- пировка взаимосвязанных выражений В литературе мысли группируются в абзацы. Хорошо написанный абзац содер- жит предложения, относящиеся только к определенной идее. Он не должен со- держать посторонних предложений. Точно так же абзац кода должен содержать только взаимосвязанные операторы, выполняющие одно задание. Пустые строки Кроме необходимости группировать взаимосвязанные опера- торы, очень важно отделять несвязанные выражения друг от друга. Начало ново- го абзаца в книге обозначается отступом или пустой строкой. Начало нового аб- заца в коде нужно указывать с помощью пустой строки. Пустые строки позволяют продемонстрировать организацию программы. Вы можете использовать их для деления групп взаимосвязанных операторов на аб- зацы, отделения методов друг от друга и выделения комментариев. Хотя эту статистику тяжело применить на практике, но одно исследова- ние показало, что оптимальное число пустых строк в программе состав- ляет от 8% до 16%. Если оно больше 16%, то время, затрачиваемое на от- ладку, заметно увеличивается (Gorla, Benander and Benander, 1990). Перекрестная ссылка Некото- рые исследователи проводят аналогии между структурой книги и структурой программы (см. подраздел «Книжная пара- дигма документирования про- грамм» раздела 32.5). |