The Robert C. Martin Clean Code Collection

1. Чистый код необходим для устойчивой разработки программного обеспечения

"Чистый код всегда выглядит так, будто его написал человек, которому не безразлично."

Качество кода имеет значение. Чистый код — это не только эстетика; это создание программного обеспечения, которое легко понять, поддерживать и расширять со временем. Когда код чистый, работать с ним — одно удовольствие, что снижает когнитивную нагрузку на разработчиков и позволяет им сосредоточиться на решении проблем, а не на расшифровке запутанных реализаций.

Технический долг дорого обходится. Пренебрежение чистотой кода приводит к накоплению технического долга, что может серьезно затруднить дальнейшую разработку и привести к остановке проектов. Постоянно пиша чистый код, команды могут избежать ловушек спешных, неаккуратных реализаций и гарантировать, что их программное обеспечение останется адаптируемым к изменяющимся требованиям.

Характеристики чистого кода:

• Читаемость и выразительность
• Хорошая организация и структура
• Соблюдение последовательных соглашений
• Легкость в понимании и модификации
• Тщательное тестирование

2. Значимые имена имеют решающее значение для читаемости и поддерживаемости кода

"Имя переменной, функции или класса должно отвечать на все важные вопросы."

Имена передают намерение. Выбор подходящих имен для переменных, функций и классов — один из самых критических аспектов написания чистого кода. Хорошие имена должны четко сообщать о цели и поведении элемента кода, который они представляют, что облегчает другим разработчикам (включая ваше будущее «я») понимание функциональности кода с первого взгляда.

Избегайте запутанных аббревиатур. Хотя может быть соблазнительно использовать короткие, сокращенные имена для экономии времени, это часто приводит к путанице и снижению читаемости. Выбирайте описательные, недвусмысленные имена, которые полностью передают значение и цель элемента кода. Помните, что современные IDE облегчают работу с длинными именами благодаря автозаполнению и инструментам рефакторинга.

Рекомендации по выбору хороших имен:

• Используйте имена, раскрывающие намерение
• Избегайте дезинформации или вводящих в заблуждение имен
• Делайте значимые различия
• Используйте произносимые имена
• Используйте имена, по которым можно искать
• Избегайте кодировок или префиксов (например, венгерская нотация)
• Выбирайте имена на соответствующем уровне абстракции

3. Функции должны быть маленькими, сосредоточенными и выполнять одну задачу хорошо

"Функции должны делать одно дело. Они должны делать это хорошо. Они должны делать это только."

Маленькие функции — это красиво. Держите функции короткими и сосредоточенными на одной задаче или концепции. В идеале функции не должны превышать 20 строк, большинство из них должно быть гораздо короче. Это делает их легче для понимания, тестирования и поддержки. Когда функция становится слишком большой или пытается сделать слишком много, это знак, что ее следует разбить на более мелкие, более сосредоточенные функции.

Принцип единственной ответственности. Каждая функция должна иметь четкую, единственную цель. Если вы обнаруживаете, что используете слова «и» или «или» для описания того, что делает функция, вероятно, она делает слишком много и должна быть разделена на несколько функций. Этот подход не только делает код более читаемым, но и более многоразовым и легким для рефакторинга.

Характеристики хороших функций:

• Выполняют одну задачу
• Имеют описательные имена
• Принимают немного аргументов (в идеале от нуля до трех)
• Не используют флаговые аргументы
• Не имеют побочных эффектов
• Соблюдают принцип единственной ответственности
• Работают на одном уровне абстракции

4. Комментарии следует использовать экономно и только при необходимости

"Правильное использование комментариев — это компенсация нашей неспособности выразить себя в коде."

Код должен быть самодостаточным. Стремитесь сделать ваш код настолько ясным и выразительным, чтобы он не нуждался в комментариях для объяснения своих действий. Хороший код с четкими именами и структурой часто более эффективен, чем комментарии, в передаче намерения. Когда вы чувствуете необходимость написать комментарий, сначала подумайте, можете ли вы рефакторить код, чтобы сделать его более очевидным.

Комментарии могут устаревать. Одна из опасностей полагания на комментарии заключается в том, что они могут устареть по мере эволюции кода, что приводит к путанице и недоразумениям. Сосредоточив внимание на написании четкого, самодокументируемого кода, вы снижаете риск ввести в заблуждение будущих разработчиков (включая себя) устаревшими комментариями.

Уместные случаи использования комментариев:

• Юридические комментарии (авторские права и т. д.)
• Объяснение намерения, когда это нельзя выразить в коде
• Уточнение сложных алгоритмов или формул
• Предупреждение о последствиях
• Комментарии TODO (экономно)
• Javadoc для публичных API

5. Правильное форматирование улучшает читаемость и понимание кода

"Форматирование кода — это о коммуникации, а коммуникация — это первоочередная задача профессионального разработчика."

Последовательность — это ключ. Установите и придерживайтесь последовательного стиля форматирования на протяжении всего вашего кода. Это включает в себя соглашения по отступам, разрывам строк, пробелам и организации элементов кода. Последовательное форматирование облегчает разработчикам быструю проверку и понимание кода, снижая когнитивную нагрузку и повышая продуктивность.

Вертикальное форматирование имеет значение. Организуйте ваш код вертикально для повышения читаемости. Держите связанные концепции близко друг к другу и отделяйте несвязанные концепции. Используйте пустые строки для создания «параграфов» в вашем коде, группируя связанные операторы и отделяя разные мысли. Эта вертикальная организация помогает читателям быстро понять структуру и поток кода.

Рекомендации по форматированию:

• Последовательные отступы (пробелы или табуляции)
• Правильные разрывы строк и пробелы
• Вертикальное выравнивание связанных элементов
• Логическая группировка связанного кода
• Последовательные соглашения по именованию
• Ограничение длины строки (например, 80-120 символов)
• Правильное размещение фигурных скобок и круглых скобок

6. Обработка ошибок должна быть тщательной и отделенной от основной логики

"Обработка ошибок важна, но если она затмевает логику, это неправильно."

Разделяйте заботы. Код обработки ошибок должен быть отделен от основной логики ваших функций. Это разделение делает как «счастливый путь», так и обработку ошибок более ясными и легкими для понимания. Рассмотрите возможность использования исключений для обработки ошибок, так как они позволяют сохранить основную логику чистой и незагроможденной.

Будьте конкретными и информативными. Когда возникают ошибки, предоставляйте четкие и конкретные сообщения об ошибках, которые помогают определить проблему и возможные решения. Избегайте общих сообщений об ошибках, которые оставляют пользователей или других разработчиков в недоумении относительно того, что пошло не так. Кроме того, рассмотрите возможность ведения журнала подробной информации об ошибках для целей отладки.

Лучшие практики обработки ошибок:

• Используйте исключения вместо кодов возврата
• Создавайте информативные сообщения об ошибках
• Определяйте классы исключений с учетом потребностей вызывающего
• Не возвращайте null
• Не передавайте null
• Предоставляйте контекст с исключениями
• Оборачивайте сторонние API для обработки их специфических исключений

7. Модульные тесты жизненно важны для поддержания качества кода и облегчения изменений

"Тестовый код так же важен, как и производственный код."

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

Пишите тесты первыми. Следуя подходу разработки через тестирование (TDD), пишите тесты перед реализацией самого кода. Эта практика помогает вам продумать дизайн и требования вашего кода перед тем, как погрузиться в реализацию. Это также гарантирует, что ваш код будет тестируемым с самого начала, способствуя лучшему дизайну и более модульному, слабо связанному коду.

Характеристики хороших модульных тестов:

• Быстрые: тесты должны выполняться быстро
• Независимые: тесты не должны зависеть друг от друга
• Повторяемые: тесты должны давать одинаковые результаты каждый раз
• Самопроверяемые: тесты должны иметь булевый вывод (успех/неудача)
• Своевременные: тесты должны писаться непосредственно перед производственным кодом
• Читаемые и поддерживаемые
• Покрывают крайние случаи и граничные условия

8. Классы должны быть маленькими, сосредоточенными и следовать принципу единственной ответственности

"Первое правило классов — они должны быть маленькими. Второе правило классов — они должны быть еще меньше."

Принцип единственной ответственности. Каждый класс должен иметь одну, и только одну, причину для изменения. Этот принцип побуждает вас создавать маленькие, сосредоточенные классы, которые легче понять, тестировать и поддерживать. Когда класс пытается сделать слишком много, его становится трудно модифицировать, и он становится более подверженным ошибкам.

Когезия имеет решающее значение. Стремитесь к высокой когезии внутри ваших классов, что означает, что методы и свойства класса должны быть тесно связаны и работать вместе для выполнения цели класса. Низкая когезия часто указывает на то, что класс пытается сделать слишком много и его следует разделить на несколько меньших, более сосредоточенных классов.

Рекомендации по созданию хороших классов:

• Держите классы маленькими (стремитесь к 100-200 строкам)
• Соблюдайте принцип единственной ответственности
• Поддерживайте высокую когезию между методами и свойствами
• Ограничьте количество переменных экземпляра
• Предпочитайте композицию наследованию
• Используйте внедрение зависимостей для управления зависимостями
• Соблюдайте принцип открытости-закрытости (открыты для расширения, закрыты для модификации)

9. Системы должны быть спроектированы с чистыми границами и разделением забот

"Оптимальная архитектура системы состоит из модульных доменов забот, каждый из которых реализован с помощью обычных объектов Java (или других)."

Четкие границы. Проектируйте вашу систему с четкими границами между различными компонентами или модулями. Это разделение позволяет каждой части системы развиваться независимо и облегчает понимание, тестирование и поддержку отдельных компонентов. Используйте интерфейсы и абстрактные классы для определения этих границ и скрытия деталей реализации.

Управление зависимостями. Тщательно управляйте зависимостями между различными частями вашей системы. Используйте внедрение зависимостей и инверсию управления, чтобы разъединить компоненты и сделать их более модульными. Этот подход облегчает изменение или замену частей системы без влияния на другие.

Стратегии для чистого проектирования системы:

• Используйте многослойную архитектуру (например, представление, бизнес-логика, доступ к данным)
• Применяйте принцип инверсии зависимостей
• Используйте шаблоны проектирования для решения общих проблем
• Создавайте абстракции для скрытия деталей реализации
• Используйте аспектно-ориентированное программирование для кросс-вычислений
• Реализуйте архитектуру плагинов для расширяемости
• Отделяйте конфигурацию от кода

10. Непрерывное улучшение через рефакторинг — ключ к поддержанию чистого кода

"Акт написания чистого кода — это упражнение в том, чтобы взять что-то работающее и очистить его, пока оно не будет соответствовать правилам."

Рефакторинг — это непрерывный процесс. Чистый код не достигается за один раз, а требует постоянного улучшения и рефакторинга. По мере получения новых знаний или изменения требований будьте готовы пересмотреть и уточнить свой код. Регулярный рефакторинг помогает предотвратить накопление технического долга и поддерживать ваш код в состоянии, пригодном для обслуживания.

Правило скаута. Следуйте правилу скаута: "Оставляйте лагерь чище, чем вы его нашли." Каждый раз, когда вы работаете над кусочком кода, старайтесь улучшить его, даже если это всего лишь небольшое улучшение. Со временем эти небольшие улучшения складываются в значительные достижения в качестве кода и его поддерживаемости.

Техники рефакторинга:

• Извлечение метода: разбейте длинные методы на более мелкие, сосредоточенные
• Переименование: улучшите имена переменных, методов и классов
• Перемещение метода: переместите методы в более подходящие классы
• Извлечение класса: разделите большие классы на меньшие, сосредоточенные
• Встраивание метода: упростите код, убрав ненужные абстракции
• Замените условие полиморфизмом
• Введите объект параметров: сгруппируйте связанные параметры
• Устраните дублирование: исключите повторяющийся код

Последнее обновление: October 1, 2024