Распространенные ошибки

Типичные ошибки

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

— Загадочные имена. Хорошая загадка уместна где угодно, но не в правилах написания кода. Классам, методам и переменным нужны понятные, однозначные имена. Подробнее см. раздел об именовании. — Избыточная сложность. Чрезмерное проектирование возникает, когда класс пытаются заранее подготовить ко всем возможным потребностям. Так появляется «божественный объект» (God object) с длинными методами или огромный класс, который делает слишком много. Разделите монолитный класс на небольшие специализированные части, каждая из которых отвечает за одну задачу. — Негибкость. Небольшое изменение не должно требовать множества исправлений в других местах. Если это происходит, проверьте, не нарушен ли принцип единственной ответственности.

Объект с несколькими обязанностями ломается чаще, потому что предусмотреть все взаимодействия сложнее. Если метод выполняет одну задачу и после изменения по-прежнему работает правильно, остальная система также должна продолжить работу.

— Хрупкость. Если после небольшого изменения перестает работать вся система, это часто указывает на проблему в структуре кода. — Неподвижность. Код нередко можно повторно использовать в другом контексте. Если перенести его мешает большое число зависимостей, отделите основную логику от окружения.

— Дублирование кода. Если видно, что код скопирован и вставлен, пора выполнить рефакторинг. Вынесите общую логику в отдельный метод и вызывайте его из остальных методов. Копии сложно сопровождать: при каждом изменении приходится исправлять несколько мест. Подробнее см. раздел о принципе DRY.

— Избыточные комментарии. Они помогают объяснить неочевидный код, но ими легко злоупотребить. Пошаговые пояснения к каждой переменной или инструкции не нужны. Лучше дать методу или классу имя, ясно выражающее намерение. Чем меньше и понятнее фрагменты логики, тем меньше пояснений им требуется.

Common pitfalls

Clean code isn’t an accident. It’s the deliberate work of individuals trying to think and code like a team. Not everything goes to plan, of course. Unclean code inevitably happens, no matter how hard you might try. You’ll need to be on the hunt for it. A code smell is a telltale sign you might have troublesome code lurking in the project. Though the following symptoms don’t necessarily point to underlying problems, they are worth investigating when they appear: —

Enigmatic naming: Everyone loves a good mystery, except in their coding standards. Classes, methods, and variables need straightforward, no-nonsense names. See the naming section for more information.

Needless complexity: Over-engineering happens when you try to anticipate every possible need for a class. This can manifest itself as a God object with long methods or large classes that try to do too much. Break up a large monolithic class into smaller dedicated parts, each with its own responsibility.

Inflexibility: A small change should not require you to make multiple changes elsewhere. Double-check that you aren’t breaking the single-responsibility principle if that’s the case. When you give something more than one responsibility, it breaks more easily because it’s harder to anticipate everything. If you update a method that is doing one thing, and the updated logic still works, you expect the rest of your code to continue to work afterward.

Fragility: If you make a minor change and everything stops working, this often indicates a problem.

Immobility: You’ll often write code that is reusable in a different context. If it requires many dependencies to deploy elsewhere, then decouple how the logic works.

Duplicate code: If it’s noticeable that you’ve cut and pasted code, it’s time to refactor. Extract the core logic into its own function and call that from the other functions. Copyand-paste code is difficult to maintain because you need to update the logic in multiple locations each time there is a change. See the section on DRY principles for more information.

Excessive commentary: Comments can help explain code that isn’t intuitive. However, developers can overuse them. A running commentary for every variable or statement is unnecessary. It’s better to have a well-named method or class where the name reveals the intent and no comment is needed. If you split your logic into smaller pieces, the shorter code snippets require less explanation.