Оригинальная статья

Контрольный список для хорошего программирования

Рафаэль А. Финкель

Департамент компьютерных наук

Университет Кентукки

Этот контрольный список должен помочь вам написать высококачественные программы.
Рафаэль Финкель, 17 августа 2005 г.

• Идентификаторы: убедитесь, что все ваши идентификаторы значимы.
  1. Однобуквенные идентификаторы почти никогда не имеют смысла.
  2. Такие имена, как flag и temp , редко имеют смысл. Вместо flag рассмотрите возможность назвать логическое условие, которое он проверяет, например, valueFound .
  3. Рассмотрите идентификаторы из нескольких слов, такие как nameIndex . Длинные идентификаторы (в пределах разумного), как правило, очень удобочитаемы.
• Чистые литералы: Избегайте в своей программе чисел, отличных от 0 и 1, и строк, отличных от “”, за исключением случаев, когда вы определяете константы.

• 1. Не используйте литеральное целое число в качестве привязки массива.
  2. Не используйте литеральное целое число в качестве параметра запуска, например время ожидания или номер порта.
  3. Не используйте литеральные целые числа для выбора пунктов меню.
  4. Не используйте литеральное целое число для измерения размера строки или некоторых данных; используйте sizeof() и strlen() в C и C++ и .length() и .size в Java.
  5. Не используйте литеральную строку для имени файла. Однако вы можете выводить литеральные строки.
  6. Не используйте литеральное целое число для индексации массива, содержащего разнородные данные.
  7. Не объявляйте идентификатор с именем, обозначающим литерал, например, «тридцать».

• Модуляризация: программа строится из взаимодействующих компонентов.

• 1. Не помещайте весь свой код в процедуру main() .
  2. На самом деле, не заставляйте любую программу делать слишком много работы. Если она длиннее примерно 50 строк, возможно, она слишком длинная.
  3. Если вы дублируете код несколько раз, подумайте, будет ли лучше работать цикл или, возможно, или лучше подпрограмма.
  4. Если вы обнаружите, что делаете очень глубокие отступы, скорее всего, вы не используете подпрограммы, когда должны.
  5. Не изобретайте библиотечные процедуры заново (если этого не требует ваше задание). Посмотрите руководства, чтобы узнать, например, о sprintf() и atoi() .
  6. Используйте заголовочные файлы в C и C++ (заголовочные файлы имеют имена, заканчивающиеся на .h ), чтобы определить все константы, необходимые для нескольких файлов, и объявить все подпрограммы, экспортируемые между файлами. Но не помещайте тело подпрограмм в файлы заголовков (за редким исключением встроенных подпрограмм).

• Форматирование: Ваша программа должна легко читаться.

• 1. Посмотрите на http://geosoft.no/development/javastyle.html четкие рекомендации по форматированию и другим вопросам представления. Этот справочник специально предназначен для Java, но имеет значение и для других языков.
  2. Попробуйте ограничить все свои строки до 80 символов; многие люди просматривают код в окнах с 80 столбцами по историческим причинам.
  3. Не используйте для отступа вместе и табуляцию, и пробелы, потому что не все текстовые редакторы воспринимают табуляцию ровно как 8 пробелов.
  4. Следуйте согласованному шаблону отступов, отражающему структуру управления программы.
  5. Не добавляйте в программу много пустых строк. Достаточно одной пустой строки между подпрограммами.
  6. Разные операционные системы завершают строки по-разному. Если вы переключаетесь между Win32 (использующей \r\n), Unix (использующей \n) и MacOS (использующей \r), переформатируйте файл, чтобы использовать согласованный метод завершения.
  7. Не устанавливайте исполняемый бит (Unix) в исходных файлах.

• Кодирование: вы хотите, чтобы ваш код был чётким, удобным и эффективным, именно в таком порядке. Некоторые правила здесь очень специфичны; другие являются более общими.

• 1. Не используйте последовательность операторов if , в которой нет else , если только один из них может совпасть; используйте else if .
  2. Если вы хотите классифицировать ввод текста, не перечисляйте возможные первые символы.
  3. Используйте операторы сдвига вместо умножения для построения битовых комбинаций.
  4. В операторе switch всегда проверяйте регистр по умолчанию. Точно так же в последовательности операторов if–then–else используйте финалльный  else .
  5. Все системные вызовы могут завершиться ошибкой. Всегда проверяйте код возврата и используйте perror() , чтобы сообщить об ошибке.
  6. Логические значения всегда должны использовать тип boolean в Java, bool в C++ и целые числа 0/1 в C. Не используйте символы t и f и не используйте -1 и 1.
  7. Используйте циклы для инициализации структур данных, если это возможно.
  8. Используйте каждую переменную и каждое поле структуры ровно для одной цели. Не перегружайте их, если для этого нет веской причины.
  9. Не используйте один и тот же идентификатор для типа, переменной и имени файла, даже если вы меняете регистр символов. Это слишком запутанно.
  10. Если вы изменяете данные с помощью htonl() или аналогичной процедуры перед передачей по сети, не изменяйте данные на месте. Создайте вторую структуру данных.
  11. Старайтесь не использовать глобальные или нелокальные переменные. Объявите каждую переменную в минимально возможной области видимости. Нелокальные переменные допустимо использовать, но убедитесь, что они вам действительно нужны.
  12. Программы Shell, Perl и Python должны иметь свой #! строка как первая строка файла; в противном случае строка является просто комментарием.
  13. Старайтесь избегать кодирования особых случаев. Вы часто можете использовать псевдоданные или другие методы структуры данных, которые позволяют вам складывать особые случаи в обычные.

• Компиляторы: Позвольте им помочь вам найти ошибки. Всегда вызывайте компиляторы со всеми включёнными предупреждениями.

• 1. Для C и C++ используйте флаг -Wall .
  2. Для Java используйте -Xlint:all -deprecation и используйте программу pmd , чтобы получить рекомендации по улучшению стиля.
  3. Для Python используйте -t -W all .
  4. Для Perl используйте флаг -w и укажите use strict . Скрипты Cgi-bin также должны иметь флаг -T .

• Утилита make : применяйте её, и используйте её правильно.

• 1. Makefile всегда должен иметь «чистое» предписание, которое должно удалять все файлы, которые могут быть восстановлены другими предписаниями в Makefile, включая объектные и исполняемые файлы.
  2. Если в вашем проекте несколько исходных файлов, Makefile должен генерировать объектные ( .o ) файлы по мере необходимости и связывать их вместе.
  3. Makefile должен быть написан так, чтобы, если вы запустите make два раза подряд, второй запуск не выполнял рекомпиляцию.
  4. Каждое предписание должно создавать файл, указанный в её цели.
  5. Каждое предписание должно использовать каждый файл, указанный в её списке обязательных компонентов.
  6. Научитесь использовать правила для таких целей, как .co , чтобы избежать повторяющихся make-файлов.
  7. Если у вас есть только один исходный файл C или C++, исполняемый файл должен иметь то же имя (без расширения .c или .cpp ).
  8. Убедитесь, что вы указали все файлы .h в качестве предварительных условий там, где они необходимы. Рассмотрите возможность использования makedepend для создания списка необходимых компонентов.

• Документация: Это не только для сортировщика. Это также поможет вам при написании программы!

• 1. Добавляйте документацию по мере написания программы. Вы всегда можете изменить её по мере изменения вашего дизайна.
  2. Напишите внешнюю документацию: как кому-то компилировать и запускать программу и для чего она предназначена? Внешняя документация обычно находится в отдельном файле README ; для небольших проектов это может быть комментарий в отдельном исходном файле.
  3. Включите внутреннюю документацию: какие алгоритмы и структуры данных вы используете? Обзор может быть в отдельном файле README , но обычно внутренняя документация размещается по конкретным подпрограммам, объявлениям и шагам, которые она описывает.
  4. Проверьте всю свою программу и документацию на наличие орфографических ошибок. Невежливо сдавать работу с ошибками, и это свидетельствует о невнимании к деталям.
  5. Проверьте всю свою документацию (и выходные сообщения) на наличие грамматических ошибок.
  6. Программы становятся намного более читабельными, если поставить короткий комментарий к закрывающим фигурным скобкам. Например, фигурная скобка, закрывающая условное выражение, может иметь комментарий типа «если значение выглядит хорошо». Скобка, закрывающая цикл, может иметь комментарий типа «для каждой входной строки». Скобка, закрывающая процедуру, может иметь комментарий, просто называющий процедуру. Скобка, закрывающая класс, может иметь комментарий, говорящий «класс», а затем имя класса.

Почему-то эта страница пользуется популярностью у переводчиков.