Правила хорошего тона. Рефакторинг. Неприлично чистый код. (Конспект книги Р.Мартина “Чистый код” часть 1)

Home » рефакторинг » Правила хорошего тона. Рефакторинг. Неприлично чистый код. (Конспект книги Р.Мартина “Чистый код” часть 1)
рефакторинг Комментариев нет

Эвристические правила и требования к именам, функциям, комментариям

Имена

  1. Имена должны быть содержательными, не стоит боятся длинных имен
  2. Имена не должны быть слишком абстрактными
  3. Имена не должны быть похожи на служебные слова или имена классов, если они не имеют никаких связей(например не стоит называть класс CustomersList если он не является коллекцией)
  4. Имена должны быть точными, информативными, недвусмысленными
  5. стоит избегать схем кодирования имен, информация о типе должна быть в типе!, не нужно никаких префиксов и постфиксов!
  6. длинна имени должна соответсвовать размеру его области видимости
  7. однобуквенные имена уместны только в локальных переменных в коротких методах
  8. имя не должно требовать расшифровывающего комментария
  9. имена не должны содержать избыточный контекст(неуместную на данном уровне абстракции информацию, например)

Функции

  1. Функция с одним аргументом лучше такой же с двумя – аргументы усложняют функции и лишают их значительной части их концептуальной мощи бинарные функции следует преобразовывать в унарные
  2. аргумент и имя функции часто находятся на разных уровнях абстракции что усложняет восприятие
  3. стандартные унарные формы функции: 1)проверка условия(возвращает boolean) 2)обработка, преобразование и возвращение(возвращает преобразованный полученный на входе аргумент) 3) событие -функция просто изменяет состояние системы и ничего не возвращает
  4. в унарных функция пара функция/аргумент должна образовывать естественную пару – глагол-существительное – write(name); print(surname);
  5. Функция с двумя аргументами лучше такой же с тремя
  6. Если функция содержит три и более аргументов, возможно ее следует упаковать в класс с тремя и более полями
  7. если аргументы функции равноправны, их можно представить в виде коллекции(например, List), функции с переменным списком аргументов не стоит делать больше чем с тремя-четырьмя аргументами
  8. Функция без аргументов лучше функции с одним аргументом, однако, если функция преобразует входной аргумент, то результат должен передаваться в возвращаемом значении(66*)
  9. функция должна быть компактной
  10. функция должна быть еще компактнее
  11. блоки в if while else должны содержать не более одной строки кода, – обычно вызов функции
  12. максимально в функции не должно быть более одного-двух отступов
  13. “ПРАВИЛО ОДНОЙ ОПЕРАЦИИ: Функция должная выполнять только одну операцию. Она должна выполнять ее хорошо. И ничего другого она делать не должна – функцию, выполняющую только одну операцию, невозможно осмысленно разделить на секции. Если функция выполняет только те действия, которые находятся на одном уровне под объявленным именем функции, то эта функция выполняет только одну операцию”
  14. все этапы работы функции должны находится на одном уровне абстракции(60*) – уровни абстракции в функции не должны смешиваться!
  15. сложные цепочки if, else, а также switch – желательно прятать в низкоуровневом классе, и избегать дублирования этих конструкций в коде – (проблема решается полиморфизмом!, например, фабрикой)- Конструкции Switch допустимы в коде, если встречаются в программе однократно, используются для создания полиморфных объектов и скрываются за отношениями наследования, чтобы быть невидимыми для остальных частей системы(63*)
  16. длинное содержательное имя лучше короткого и невразумительного
  17. функция должна делать только то, что следует из ее названия, она не должна иметь побочных эффектов – например, не должна менять своевольно глобальную переменную, инициализировать сессию, запускать поток – нарушение правила чревато серьезными ошибками
  18. код должен читаться сверху вниз. И быть разделен по уровням абстракции. Функции объявленные выше должны использовать функции объявленные ниже.
  19. Все что заставляет обращаться к сигнатуре функции, нарушает естественный ритм чтения кода(70*). Следует избегать “выходных аргументов”(аргументов не возвращаемых, но преобразуемых в теле функции) – Если функция изменяет чье-то состояние, – пусть она изменяет состояние объекта, своего владельца
  20. ПРИНЦИП РАЗДЕЛЕНИЯ КОМАНД И ЗАПРОСОВ: либо функция изменяет состояние объекта, либо возвращает информацию о нем, либо, либо
  21. возвращение функциями кодов ошибок является прямым нарушением принципа РАЗДЕЛЕНИЯ КОМАНД И ЗАПРОСОВ if(deletePage(page)==OK)
  22. тела блоков try и catch рекомендуется выделять в отдельные функции. Таким образом, код нормального выполнения отделяется от кода обработки ошибок. Обработка ошибок – это одна операция. Функция, обрабатывающая ошибки, ничего другого делать не должна.
  23. не стоит использовать перечисления с константами состояния(такие классы перечислений – называют магнитами зависимостей ибо при каждом обновлении списка таких состояний необходимо править код в нескольких местах сразу и перекомпиляции(73*))

Комментарии

  1. Комментарии в коде – вещь – лишняя! Код должен читаться сам по себе. Если необходимо объяснение кода – значит этот код плохой и требует рефакторинга. Лучше исправить код, чем написать комментарий. Вместо того, чтобы написать комментарий к функции, иногда лучше назвать функцию понятным описывающим ее действия именем и раскрывающим полностью ее суть
  2. комментариев следует избегать вообще!! см п. 1.
  3. юридические комментарии следует ограничивать именем автора, датой и ссылкой на лицензию, текст самой лицензии – громоздок и неуместен
  4. если конечные намерения разработчика неочевидны из кода – допускается прояснить намерения(например, различные ресурсоемкие коды теста(83*))(лучше рефакторинг конечно)
  5. если какой-то код не имзменить или он является частью библиотеки, где названия функций неочевидны допускается прояснить действия этих функций(но без злоупотреблений(84*)
  6. допускается комментарий с предупреждением о небезопасном коде(например потоково-небезопасный метод)
  7. //TODO – комментарий с пояснением используется для того чтобы описать то, что еще не реализовано но однозначно планируется реализовать(например функции)
  8. если нужно обратить внимание на важность какой-то строки или применения функции. (85*)(?)
  9. комментарии Javadoc писать везде необязательно! а только там где это действительно нужно
  10. комментарий сам не должен нуждаться в объяснениях
  11. комментарий не должен быть избыточным
  12. комментарии не должны содержать смысловых ошибок(поэтому см. п.2)
  13. применение комментария должно носить обязательный характер, оно должно быть оправданным
  14. комментарии маркеры //*********************** это моветон
  15. журнальные комментарии устарели как только появились системы контроля версий
  16. комментирование закрывающих фигурных скобок(чтобы показать где кончается какой цикл – моветон, лучше сделать рефакторинг) } //try } //while и.т.д.
  17. закомментированный код – зло
  18. ссылки на авторов устарели как только появились системы контроля версий
  19. не использовать комментарии там где можно использовать (говорящую)функцию или (говорящую)переменную!(рефакторинг)
  20. нелокальная информация(нерелевантная текущему уровню абстракции кода) не должна находиться в комментарии
  21. комментарии должны быть очевидны
  22. Лучше много коротких функций, чем одна большая с туманным комментарием
  23. Заголовки Javadoc не нужны во внутреннем коде.

Правила хорошего тона

1) не используем общие исключения. Общие исключения потребляют много памяти
2) в блоке catch не используем system.out.println, используем printstacktrace, то бишь трассировку стека или же логи – system.error.println
3) классы – существительные, функции – глаголы

Тестовый код помечается аннотацией @Ignore

*-номер страницы с отсылкой на правило из книги Р. Мартина “Чистый код”

LEAVE A COMMENT