Комментарии vs. самодокументируемый код: что выбрать?

Если вы когда-либо сталкивались с чужим кодом (или даже со своим, написанным полгода назад), то знаете, как сложно бывает понять, что именно делает тот или иной фрагмент. В такие моменты особенно остро ощущается потребность в пояснениях. Но какие есть способы, помогающие сделать код понятным?

Разберемся вместе.

Когда автор этих строк делал первые шаги в программировании, одним из основных языков был ассемблер. В те времена подробные комментарии к каждой строке считались необходимостью — не столько по привычке, сколько по объективной сложности самого языка. Понять ассемблерный код без пояснений было практически невозможно.

С тех пор многое изменилось: большинство задач теперь решается с использованием языков высокого уровня. И вместе с этим возникает закономерный вопрос — действительно ли нам всё еще нужны комментарии? Или современный код может (и должен) объяснять себя сам?

---

Почему комментарии — не всегда добро

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

Во-первых, они устаревают. Код меняется, бизнес-логика эволюционирует, а комментарии… забываются. И вот уже в тексте говорится одно, а код делает совершенно другое.

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

Во-вторых, они часто маскируют проблему. Вместо того чтобы улучшить читаемость, разработчик просто дописывает комментарий к непонятной строке. Это сигнал: коду не хватает выразительности.

---

Что такое самодокументируемый код

Самодокументируемый код — это стиль написания, при котором смысл заложен в самом коде, а не в сопровождающем тексте.

В чём его сила:

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

• Мелкие, логичные методы. Сложность разбивается на части, каждая из которых выполняет одну понятную задачу.

• Минимум сюрпризов. Читая такой код, вы чувствуете себя уверенно. Он ведет за собой, как хорошо написанная инструкция.

---

Когда код говорит сам за себя: несколько примеров

💬 Было:

// Вычисляем общую стоимость заказа с учетом налогов и скидок public double calculate(double price, double tax, double discount) {     return price + (price * tax) - discount; } 

🧾 Стало:

public double calculateTotalOrderPrice(double price, double taxRate, double discountAmount) {     return price + (price * taxRate) - discountAmount; } 

Комментарий исчез — но смысла стало даже больше. Имя метода и параметры делают всё понятным с первого взгляда.

---

Еще пример:

💬 Было:

# Проверяем, является ли число чётным if number % 2 == 0:     print("Четное") 

🧾 Стало:

def is_even(number):     return number % 2 == 0  if is_even(number):     print("Четное") 

Появилась функция с хорошим именем — и вот уже комментарий не нужен. Понимание приходит сразу.

---

А как быть со сложной логикой?

Самодокументируемый код особенно хорош, когда дело доходит до предикатов.

💬 Было:

// Проверяем, если пользователь не заблокирован и подписка активна if (!user.isBlocked && user.subscription.isActive) {     sendNewsletter(); } 

🧾 Стало:

if (user.canReceiveNewsletter()) {     sendNewsletter(); } 

Метод canReceiveNewsletter() говорит сам за себя. Условие скрыто — но смысл раскрыт. Такой подход не только улучшает читаемость, но и упрощает повторное использование логики.

---

Что говорит об этом «Чистый код»

Роберт Мартин в своей книге «Чистый код» настойчиво подчеркивает: лучший комментарий — это тот, который не нужен. Если код требует пояснений — это сигнал, что его можно улучшить.

Он призывает:

• Извлекать методы с понятными названиями.

• Давать осмысленные имена переменным.

• Избегать лишних комментариев.

• Делать код максимально прозрачным и понятным.

---

Но не все так однозначно

Это не значит, что комментарии должны исчезнуть навсегда. Иногда они необходимы:

• Чтобы объяснить почему сделано именно так, а не иначе.

• Чтобы задокументировать сторонние ограничения.

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

Но они должны быть исключением, а не правилом.

---

Заключение

Хороший код — как хороший текст: он читается легко, рассказывает о себе сам и не вызывает лишних вопросов. И хотя комментарии могут помочь, по-настоящему выразительный, самодокументируемый код делает их почти ненужными.

Следующий раз, когда потянетесь к //, спросите себя: а можно ли сделать код настолько понятным, чтобы он сам за себя говорил?

Скорее всего — можно.