Контрольный список: форматирование

[@McConnell2004]

Общие вопросы

  • Применяется ли форматирование в основном для логического структурирования кода?
  • Может ли схема форматирования применяться единообразно?
  • Позволяет ли форматирование получить код, который легко сопровождать?
  • Улучшает ли схема форматирования читаемость кода?

Управляющие структуры

  • Содержит ли код двойные отступы в парах begin-end или {}?
  • Отделяются ли последовательные блоки друг от друга пустыми строками?
  • Форматируются ли сложные выражения с учетом удобочитаемости?
  • Форматируются ли блоки из одного оператора единообразно?
  • Согласуется ли стиль форматирования операторов case с форматированием других управляющих структур?
  • Отформатированы ли операторы goto так, что их применение очевидно?

Отдельные операторы

  • Применяются ли пробелы для повышения удобочитаемости логических выражений, обращений к массивам и аргументов методов?
  • Выглядит ли конец строки с незавершенным оператором очевидно некорректным?
  • Сделан ли при переносе строк отступ стандартного размера?
  • Не содержит ли каждая строка более одного оператора?
  • Не содержат ли операторы побочных эффектов?
  • Не содержит ли каждая строка более одного определения данных?

Комментарии

  • Сделаны ли в комментариях отступы такого же размера, как и в коде, который они комментируют?
  • Легко ли сопровождать принятый стиль комментариев?

Методы

  • Отформатированы ли аргументы всех методов так, что каждый из них легко читать, исправлять и комментировать?
  • Используются ли пустые строки для разделения составных частей метода?

Классы, файлы и программы

  • Существует ли однозначное соответствие между классами и файлами для большинства классов и файлов?
  • Если файл содержит несколько классов, сгруппированы ли методы каждого класса вместе, и можно ли четко выделить каждый класс?
  • Разделяются ли методы в файле пустыми строками?
  • Вместо более строгого организационного принципа не стоит ли упорядочить все методы по алфавиту?

Ключевые моменты

  • Главная цель визуального форматирования — это подчеркивание логической структуры кода. В критерии оценки достижения этой цели входят аккуратность, единообразие, удобство чтения и сопровождения кода.
  • Критерий хорошего внешнего вида имеет вторичное, далеко не основное значение. Однако если другие критерии соблюдены, а лежащий в основе код написан хорошо, то форматирование будет выглядеть привлекательно.
  • Visual Basic поддерживает явные блоки, а стандартное соглашение в Java предписывает их использование, поэтому, программируя на этих языках, вы можете применять явные блоки. В C++ хорошо смотрится эмуляция явных блоков или обозначение границ блоков с помощью пар begin-end.
  • Структурирование кода само по себе имеет большое значение. Конкретные соглашения менее важны, чем сам факт, что вы последовательно применяете определенные соглашения. Договоренности по форматированию, соблюдаемые лишь от случая к случаю, могут сильно ухудшить читаемость кода.
  • Многие аспекты форматирования сродни религиозным вопросам. Пытайтесь разделять объективные и субъективные предпочтения. Используйте явные критерии для обоснования вашей точки зрения при обсуждении стилевых предпочтений.