Прочитал «Чистый код», чтобы вам не пришлось

Качество кода — Критический фактор успеха любого программного проекта. Некорректные наименования сущностей, избыточная сложность методов, противоречивые комментарии и нарушение структурных принципов ведут к существенным проблемам: снижению скорости разработки, росту количества ошибок и сложности поддержки. Роберт Мартин (известный как «Дядя Боб»), один из авторов Agile-манифеста, в своей фундаментальной работе «Чистый код» систематизировал принципы написания эффективного, поддерживаемого кода.

Книга «Чистый код» это детально проработанная методология, основанная на десятилетиях опыта разработки коммерческих систем. Она отвечает на ключевые вопросы:

• Как создать код, который понятен коллегам через месяцы после написания?

• Какие паттерны предотвращают накопление технического долга?

• Как проектировать компоненты для лёгкого тестирования и модификации?

Все примеры в этой статье будут на языке программирования C#. Каждый раздел сопровождается примерами рефакторинга «плохого» кода в «чистый» согласно стандартам Мартина.

Что такое чистый код?

Мартин начинает с фундамента: чистый код — это код, написанный с заботой о читателе (часто будущем вас или коллеге). Этот код:

• Прямолинеен: Делает ровно то, что ожидается.

• Лаконичен: Ничего лишнего. Одна операция — одна функция, одна ответственность — один класс.

• Выразителен: Имена и структура и без комментариев объясняет, что делается и почему.

• Поддерживаем: Легко изменять и расширять без страха сломать что-то ещё.

• Проверен: Покрыт осмысленными юнит-тестами.

Основа всего — имена

Правильные названия — 90% чистого кода. Вот основные правила:

1. Выразительность: Имя должно отвечать на все главные вопросы: Что это? Зачем нужно? Как используется? Избегайте общих слов (data, info, manager), если они не полностью говорят о смысле.

   • Плохо: int d; // elapsed time in days

   • Хорошо: int elapsedTimeInDays;

   • Плохо: List list1;

   • Хорошо: List activeCustomers;

2. Избегайте дезинформации:
   Не используйте accountList для переменной типа Account[] (это не список). Лучше accounts или accountGroup.
   Не используйте похожие имена: XYZControllerForEfficientHandlingOfStrings и XYZControllerForEfficientStorageOfStrings.

3. Делайте осмысленные различия:

   • Плохо: Product, ProductInfo, ProductData (что отличает их?).

   • Плохо: a1, a2, ... aN.

   • Хорошо: sourceCustomer, targetCustomer; originalMessage, encryptedMessage.

4. Используйте произносимые имена: genymdhms (generate date, year, month, day, hour, minute, second) — кошмар. Лучше generationTimestamp.

5. Используйте поисковые имена: Однобуквенные имена (i, j, k в коротких циклах — исключение) и числовые константы (15) сложно найти в коде.

   • Плохо: if (employee.Flags & 15) ... 

   • Хорошо: const int IsFullTimeFlag = 0x01; const int IsOnProbationFlag = 0x02;

6. Классы / Типы: Имена существительных или существительных с уточнением (Customer, AddressParser, AccountService). Избегайте Manager, Processor, Data, Info.

7. Методы: Имена глаголов или глагольных фраз (Save(), Delete(), ParseConfiguration(), CalculateTotal()). Геттеры/сеттеры — GetName(), SetName().

8. Булевы переменные / методы: Используйте префиксы is, has, can, should для ясности: isActive, hasLicense, canExecute, shouldValidate.

Методы и функции

Маленькие, хорошо организованные методы это главное чистого кода!

1. МАЛЕНЬКИЕ! И ещё раз МАЛЕНЬКИЕ!

   • Идеал: Не длиннее 20 строк. Часто 3-4 строки.

   • Правило экрана: Функция должна полностью помещаться на одном экране без прокрутки.

2. Делайте одно дело (The Single Responsibility Principle — SRP для функций):

   • Функция должна делать ТОЛЬКО то, что явно следует из ее имени. Если вы можете выделить другую операцию с осмысленным именем — вынесите ее в отдельную функцию.

   • Уровни абстракции: Операции внутри функции должны быть на ОДНОМ уровне абстракции. Не смешивайте высокоуровневую логику (ProcessOrder()) с низкоуровневыми деталями (ParseOrderLineItemString()).

3. Структура кода (Сверху-Вниз — Stepdown Rule):

   • Код должен читаться как повествование, сверху вниз.

   • На верхнем уровне высокоуровневые функции (шаги алгоритма).

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

4. Аргументы Функций (Параметры):

   • Идеал: 0 (niladic) > 1 (monadic) > 2 (dyadic). 3 (triadic) — Избегать! > 3 — Требует исключительного обоснования.

   • Флаги как аргументы — ЗЛО! (Process(bool isAdmin)) — Это явный признак, что функция делает два разных дела! Разбейте на две: ProcessAdmin(), ProcessUser().

   • Output-параметры (out, ref) — Еще большее зло! Они запутывают и нарушают поток чтения. Возвращайте кортежи или маленькие объекты-результаты.

   • Объекты-аргументы: Если нужно много параметров, логически связанных, объедините их в класс/структуру.

     • Плохо: public void CreateReservation(DateTime start, DateTime end, int roomId, string customerName, bool hasPremium)

     • Хорошо:
       public class ReservationRequest
{
public DateTime Start { get; set; }
public DateTime End { get; set; }
public int RoomId { get; set; }
public CustomerInfo Customer { get; set; } // CustomerInfo содержит Name и HasPremium
}
public void CreateReservation(ReservationRequest request)

5. Глаголы и ключевые слова:

   • Один аргумент: Имя функции и аргумента должны образовывать естественную пару глагол/существительное: WriteField(name), AssertExpectedEqualsActual(expected, actual).

   • Два аргумента: Порядок должен следовать общепринятому: Point p = new Point(x, y);.

6. Исключения вместо кодов ошибок:

   • Плохо: Возврат кодов ошибок (int result = Save(); if (result == ERROR) ...) ведет к загромождению кода проверками сразу после вызова.

   • Хорошо: Бросайте исключения (try { Save(); } catch (SaveException ex) ...). Обработка ошибок отделена от основной логики.

   • Try[Операция]Паттерн: Для ситуаций, где ошибка это часть ожидаемого потока (например, проверка пароля), используйте паттерн TryParse:
     if (int.TryParse(input, out int value)) { ... } // Успех
else { ... } // Ошибка, но не исключение

7. DRY (Don’t Repeat Yourself): Безжалостно устраняйте дублирование кода, выделяя общую функциональность в методы.

Пример рефакторинга функции (C#):
Грязный метод:

Чистые методы:

Комментарии

Лучший комментарий — отсутствующий комментарий. Хороший код объясняет себя сам через имена и структуру. Комментарии часто лгут (код меняется, а комментарии нет) и загромождают. Но есть исключения:

1. Законные комментарии:

   • Правовые: Лицензии, авторские права.

   • Поясняющие намерение (WHY): Почему код сделан так, а не иначе? Особенно если причина неочевидна (баг в библиотеке, специфичное требование).

     

   • Предупреждения о последствиях: // Внимание: Этот метод запускает долгую операцию (до 5 мин). Не вызывать из UI-потока!

   • TODO: Краткие заметки о том, что нужно доделать / поправить позже. Обязательно указывайте контекст / причину.

     

   • Усиление (Amplification): Подчеркнуть важность чего-то неочевидного. // Не изменять порядок инициализации: компонент Y зависит от X!

   • Javadoc в Public API: Для публичных методов/классов библиотек — объяснение, что делает, параметры, возвращаемое значение, исключения.

2. Недопустимые комментарии:

   • Закомментированный код: Удаляйте его! Системы контроля версий хранят историю.

   • Избыточные:

     

   • История изменений:

     

   • Скобочные / позиционные: // Конец метода CalculateTotal ------------------------

   • Комментарии-извинения: // Извините за этот баг...

   • Неясные ссылки: // См. замечание в мануале — Какой мануал? Какое замечание?

Форматирование

Единый стиль форматирования критически важен для читаемости.

1. Вертикальное форматирование (Длина файла, пустые строки, группировка):

   • Длина файла: Стремитесь к маленьким файлам (200-500 строк). Большие классы — признак нарушения SRP.

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

   • Вертикальная Близость: Связанные концепции должны быть рядом. Переменная объявляется как можно ближе к месту использования. Вызываемые методы — ниже вызывающих (Правило Stepdown).

2. Горизонтальное форматирование (Длина строки, отступы, пробелы):

   • Длина строки: 120 символов — разумный максимум. Избегайте горизонтальной прокрутки.

   • Отступы (Indentation): Обязательны! Используйте отступы (обычно 4 пробела) для вложенных блоков (внутри классов, методов, циклов, условий).

   • Пробелы: Используйте для улучшения читаемости:

     • Вокруг операторов (=, +, -, *, /, %, ==, !=, >, <, >=, <=, &&, ||): int sum = a + b;

     • После запятых в списках аргументов/параметров: void Print(string name, int age)

     • После ключевых слов (if, for, while, switch, catch): if (condition)

     • Между скобками и содержимым (кроме пустых): list.Add( item ); -> list.Add(item);

     • Не ставьте пробелы между именем методы и открывающейся скобкой: Save() (не Save ()). А также внутри скобок индексатора: array[0] (не array[ 0 ])

   • Выравнивание: Избегайте выравнивания переменных по типу или значению. Оно создаёт ложный акцент и сложно поддерживается.

     • Плохо:

       

     • Хорошо:

       

Объекты и структуры данных

• Абстракция и сокрытие данных: Классы должны скрывать свои данные и предоставлять абстрактные интерфейсы для работы с ними. Не создавайте просто структуру данных с публичными полями (в C# для этого есть struct, но и их поля лучше делать приватными).

  • Плохо (публичные поля):

    

  • Хорошо (инкапсуляция):

  

• Закон Деметера (Principle of Least Knowledge): Метод объекта M объекта O должен вызывать только методы:

  1. Самого объекта O (this).

  2. Объектов, переданных в M в качестве параметров.

  3. Объектов, созданных внутри M.

  4. Компонентов объекта O.

     • Не objectA.GetObjectB().DoSomething(); — Это «поездка по цепочке». Нарушает инкапсуляцию, делает код хрупким.

     • Решение: Делегирование. Пусть objectA предоставит метод, выполняющий нужное действие, скрыв свою зависимость от ObjectB:
       Плохо:

       

       Хорошо:

       

Обработка ошибок

Ошибки — часть жизни ПО. Обрабатывайте их чисто:

1. Используйте исключения, а не коды ошибок.

2. Сначала пишите Try-Catch-Finally: Обрабатывайте код, который может выбросить исключение, блоком try. Обрабатывайте конкретные исключения в catch. Освобождайте ресурсы в finally.

3. Не возвращайте null! Это источник NullReferenceException (для C#, аналогично в других языках). Возвращайте пустые коллекции (Enumerable.Empty(), new List()), используйте Nullable<T> для значимых типов, применяйте паттерн Null Object.

4. Не передавайте null! Это смещает ответственность за проверку на вызывающего. Бросайте ArgumentNullException в начале метода, если null недопустим.

Использование стороннего кода

Работа с библиотеками/API требует аккуратности:

1. Изолируйте границы: Не позволяйте стороннему коду «расползаться» по всей вашей кодовой базе. Оберните его в адаптер (Adapter или Facade паттерн).

   

2. Изучайте через тесты: Напишите небольшие юнит-тесты для сторонней библиотеки перед интеграцией. Это поможет понять её поведение и защитит от неожиданных изменений при обновлении.

Юнит-Тесты. TDD и чистота тестов

Без тестов нет чистого кода. Тесты обеспечивают безопасность рефакторинга.

1. TDD (Test-Driven Development) цикл:

   1. Красный: Напишите маленький тест для новой функциональности. Он должен упасть (так как функциональности ещё нет).

   2. Зелёный: Напишите минимальный код, чтобы тест прошёл. Можно схитрить.

   3. Рефакторинг (Синий): Улучшите структуру кода (как продакшн, так и тест), удалите дублирование, примените принципы чистого кода. Тесты должны оставаться зелёными.

2. Правила чистых тестов (F.I.R.S.T.):

   • F (Fast): Тесты должны выполняться мгновенно (секунды, а не минуты). Медленные тесты не запускают часто.

   • I (Independent): Тесты не должны зависеть друг от друга. Порядок выполнения не важен. Сброс состояния перед каждым тестом.

   • R (Repeatable): Результат теста одинаков в любой среде (dev, CI, продакшн) и при любом количестве запусков. Нет зависимостей от сети, времени, случайных чисел.

   • S (Self-Validating): Тест должен выдать бинарный результат: УСПЕХ или ПРОВАЛ. Нет ручной проверки логов.

   • T (Timely): Пишите тесты либо до написания кода (в подходе TDD), либо немедленно после написания рабочего кода. Никогда не откладывайте написание тестов на потом!

3. Качество тест-кода: Так же важно, как и продакшн код. Применяйте все правила чистого кода: выразительные имена, маленькие функции, минимальные утверждения (Asserts) на тест, отсутствие дублирования (используйте SetUp / TearDown или фабричные методы аккуратно), ясность (Build-Operate-Check паттерн).

   

Классы

1. Принцип единственной ответственности (Single Responsibility Principle — SRP): У класса должна быть только одна причина для изменения. Если класс делает слишком много, его нужно разбить.
   Признаки нарушения SRP: Много несвязанных методов/полей, частые изменения в разных местах класса по разным причинам, большой размер.

2. Инкапсуляция: Скрывайте данные и детали реализации! Делайте поля приватными. Предоставляйте доступ через методы / свойства. Ослабляйте уровень доступа только при явной необходимости.

3. Композиция прежде наследования (Composition over Inheritance): Наследование создаёт сильную связь между классами. Часто композиция (включение одного класса в другой как поле) + интерфейсы дают больше гибкости.

   • Плохо:

     

   • Хорошо:

     

Системы

Чистота на уровне архитектуры.

1. Разделение забот (Separation of concerns): Система должна быть разделена на слабо связанные модули (например, по слоям: UI, бизнес-логика, доступ к данным). Каждый модуль решает свою задачу.

2. Чистая архитектура (Clean Architecture/Onion/Hexagonal): Основная идея — зависимости направлены внутрь, к ядру. Бизнес-правила (самые стабильные) в центре. Инфраструктура (БД, UI, фреймворки — часто меняющиеся) на периферии. Ядро не зависит от деталей реализации периферии. Достигается через интерфейсы и DI.

3. Внедрение зависимостей (Dependency Injection — DI, дополнительно Zenject): Классы не создают свои зависимости, а получают их извне (через конструктор, свойства, методы). Это ослабляет связность, упрощает тестирование и делает код гибче.

   

4. Масштабирование: Система должна начинаться с простой, чистой архитектуры. Не добавляйте сложности «на вырост»! Рефакторите и расширяйте архитектуру по мере реальной необходимости.

Пример рефакторинга

Мартин детально разбирает эволюцию небольшой программы (генератор простых чисел) от грязной первой версии до чистого кода. Этапы:

1. Начало: Рабочая, но ужасно написанная версия.

2. Написание тестов: Покрытие функциональности тестами для безопасности изменений.

3. Рефакторинг волнами:

   • Разбиение огромного метода на маленькие.

   • Улучшение имён переменных и функций.

   • Устранение дублирования.

   • Упрощение логики.

   • Улучшение алгоритма.

4. Результаты: Код становится в разы короче, понятнее, эффективнее и легче для изменения.

Словарик терминов

1. Чистый код (Clean code) — Код, который легко читать, понимать и изменять. Обладает свойствами: прямолинейность, лаконичность, выразительность, поддерживаемость, проверенность.

2. Выразительность (Expressiveness) — Свойство кода, при котором имена переменных / методов / классов и структура однозначно передают их назначение и логику без комментариев.

3. DRY (Don’t Repeat Yourself) — Принцип разработки «Не повторяйся». Любое знание или логика должны иметь единственное представление в системе.

4. SRP (Single Responsibility Principle) — Для функций/классов: Объект должен иметь только одну причину для изменения (выполнять одну обязанность).

5. Инкапсуляция (Encapsulation) — Сокрытие внутреннего состояния объекта и деталей реализации. Доступ к данным только через публичные методы / свойства.

6. Закон Деметры (Law of Demetr / Principle of Least Knowledge) — Метод объекта A должен взаимодействовать только с:

   • Самим A

   • Параметрами, переданными в метод

   • Объектами, созданными внутри метода

   • Непосредственными компонентами A. Запрещает цепочки вызовов: objA.GetB().DoC()

7. Исключение (Exception) — Механизм обработки ошибок, прерывающий нормальный поток выполнения и передающий управление обработчику (catch). Альтернатива кодам ошибок.

8. Null-объект (Null Object Pattern) — Паттерн, подразумевающий возврат специального объекта с нейтральным поведением вместо null (например, пустая коллекция).

9. Адаптер (Adapter Pattern) — Паттерн для преобразования интерфейса класса в другой интерфейс, ожидаемый клиентом. Используется для изоляции стороннего кода.

10. Фасад (Facade Pattern) — Паттерн, предоставляющий простой интерфейс к сложной подсистеме. Скрывает её детали реализации.

11. Юнит-тест (Unit Test) — Автоматизированный тест, проверяющий корректность работы небольшой изолированной части кода (метода, класса).

12. TDD (Test-Driven Development) — Методология разработки:
    🔴 Red → Написать падающий тест
    🟢 Green → Написать минимальный код для прохождения теста
    🔵 Refactor → Улучшить код, сохраняя зелёный статус.

13. F.I.R.S.T. — Принципы чистых тестов:

    • Fast — Быстрые

    • Independent — Независимые

    • Repeatable — Повторяемые

    • Self-Validating — Самопроверяющиеся

    • Timely — Своевременные.

14. Arrange-Act-Assert (AAA) — Паттерн структуры юнит-теста:

    • Arrange: Подготовка данных и зависимостей

    • Act: Вызов тестируемого метода

    • Assert: Проверка результата.

15. Внедрение зависимостей (DI, Dependency Injection) — Передача зависимостей объекта извне (через конструктор / свойства) вместо их создания внутри. Уменьшает связанность.

16. Чистая архитектура (Clean Architecture) — Архитектурный подход, где:

    • Бизнес-логика (ядро) не зависит от деталей (БД, UI, фреймворков)

    • Зависимости направлены к центру системы

17. Разделение забот (SoC, Separation of Concerns) — Принцип разделения программы на независимые модули, каждый из которых решает отдельную задачу (например: UI, бизнес-логика, БД).

18. Композиция (Composition) — Построение функциональности за счёт включения одних объектов в другие (предпочтительнее наследования).

19. Рефакторинг (Refactoring) — Изменение структуры кода без изменения его поведения. Цель — улучшение читаемости и упрощение поддержки.

20. Непрерывный рефакторинг (Continuous Refactoring) — Практика постоянного улучшения кода в процессе разработки.

21. Дурной запах кода (Code Smell) — Симптом проблемы в коде (например: длинный метод, дублирование, «божественный класс»).

22. Уровень абстракции (Level of Abstraction) — Степень детализации операций. Код внутри функции должен оперировать на одном уровне (например, только бизнес-логика или только технические детали).

23. Правило пошагового спуска (Stepdown Rule) — Код должен читаться сверху вниз: высокоуровневая логика -> детали реализации. Каждый уровень раскрывает подробности предыдущего.

24. Искажение (Misinformation) — Использование имён, вводящих в заблуждение (например: accountList для массива).

25. Обучающие тесты (Learning Tests) — Тесты, написанные для изучения поведения сторонней библиотеки перед её использованием в проекте.

26. Границы (Boundaries) — Места интеграции с внешними системами (библиотеки, API, устаревший код). Требуют изоляции.

27. Модуль (Module) — Логически связанная группа функций / классов (например: компонент, слой, библиотека).

28. Связанность (Coupling) — Степень зависимости между модулями. Низкая связанность — признак хорошего дизайна.

29. Зацепление (Cohesion) — Мера связанности обязанностей внутри модуля. Высокое зацепление — все элементы модуля работают на единую цель.

30. Искажение абстракции (Abstraction Leakage) — Ситуация, когда детали реализации просачиваются через абстракцию, нарушая инкапсуляцию.

---

Если понравилась статья — рекомендую подписаться на телеграм‑канал NetIntel. Там вы сможете найти множество полезных материалов по IT и разработке!