Файл: Руководство по стилю программирования и конструированию по.pdf

ГЛАВА 31 Форматирование и стиль
757
’ ищем арифметический минимум аргументов arg1 и arg2
Function Min( arg1 As Integer, arg2 As Integer ) As Integer
If ( arg1 < arg2 ) Then
Min = arg1
Else
Min = arg2
End If end Function
Пустые строки набирать легче любых других сепараторов, а выглядят они не хуже.
Этот пример содержит три пустых строки, и поэтому разделение между метода- ми выглядит заметней, чем пустые строки внутри каждого метода.
Упорядочивайте методы по алфавиту Альтернативой группировке взаимо- связанных функций может служить их размещение в алфавитном порядке. Если вы не можете разбить программу на классы или ваш редактор не позволяет легко находить функции, алфавитный подход может ускорить поиск.
Аккуратно упорядочивайте исходный файл на C++ Далее приведена типич- ная организация файла с исходным кодом на C++:
1. комментарий с описанием файла;
2. файлы, включаемые директивой #include;
3. определения констант, относящиеся к нескольким классам (если файл содер- жит несколько классов);
4. перечисления, относящиеся к нескольким классам (если файл содержит несколь- ко классов);
5. определения макросов;
6. определения типов, относящиеся к нескольким классам (если файл содержит несколько классов);
7. импортируемые глобальные переменные и функции;
8. экспортируемые глобальные переменные и функции;
9. переменные и функции, видимые только в этом файле;
10. классы, вместе с определениями констант, перечислений и типов, относящи- мися к конкретному классу.
Контрольный список: форматирование
Общие вопросы
Применяется ли форматирование в основном для логи- ческого структурирования кода?
Может ли схема форматирования применяться единообразно?
Позволяет ли форматирование получить код, который легко сопровождать?
Улучшает ли схема форматирования читаемость кода?
Управляющие структуры
Содержит ли код двойные отступы в парах begin-end или {}?
Отделяются ли последовательные блоки друг от друга пустыми строками?
Форматируются ли сложные выражения с учетом удобочитаемости?
Форматируются ли блоки из одного оператора единообразно?
http://cc2e.com/3194

758
ЧАСТЬ VII Мастерство программирования
Согласуется ли стиль форматирования операторов case с форматировани- ем других управляющих структур?
Отформатированы ли операторы goto так, что их применение очевидно?
Отдельные операторы
Применяются ли пробелы для повышения удобочитаемости логических вы- ражений, обращений к массивам и аргументов методов?
Выглядит ли конец строки с незавершенным оператором очевидно некор- ректным?
Сделан ли при переносе строк отступ стандартного размера?
Не содержит ли каждая строка более одного оператора?
Не содержат ли операторы побочных эффектов?
Не содержит ли каждая строка более одного определения данных?
Комментарии
Сделаны ли в комментариях отступы такого же размера, как и в коде, кото- рый они комментируют?
Легко ли сопровождать принятый стиль комментариев?
Методы
Отформатированы ли аргументы всех методов так, что каждый из них лег- ко читать, исправлять и комментировать?
Используются ли пустые строки для разделения составных частей метода?
Классы, файлы и программы
Существует ли однозначное соответствие между классами и файлами для большинства классов и файлов?
Если файл содержит несколько классов, сгруппированы ли методы каждо- го класса вместе, и можно ли четко выделить каждый класс?
Разделяются ли методы в файле пустыми строками?
Вместо более строгого организационного принципа не стоит ли упорядочить все методы по алфавиту?
Дополнительные ресурсы
Большинство учебников по программированию упоминает о форматировании и стиле вскользь, углубленное обсужде- ние стиля программирования встречается редко, а пробле- мы форматирования прорабатываются еще реже. Вопросам форматирования и стиля посвящены следующие публикации.
Kernighan, Brian W. and Rob Pike.
The Practice of Programming. Reading, MA: Addison-
Wesley, 1999. В главе 1 обсуждается стиль программирования на языках C и C++.
Vermeulen, Allan, et al.
The Elements of Java Style. Cambridge University Press, 2000.
Misfeldt, Trevor, Greg Bumgardner, and Andrew Gray.
The Elements of C++ Style. Cam- bridge University Press, 2004.
Kernighan, Brian W., and P. J. Plauger.
The Elements of Programming Style, 2d ed. New
York, NY: McGraw-Hill, 1978. Этот классический труд по стилю программирования
— первый в этом жанре.
http://cc2e.com/3101

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