Если вы когда-либо сталкивались с чужим кодом (или даже со своим, написанным полгода назад), то знаете, как сложно бывает понять, что именно делает тот или иной фрагмент. В такие моменты особенно остро ощущается потребность в пояснениях. Но какие есть способы, помогающие сделать код понятным?
Разберемся вместе.
Когда автор этих строк делал первые шаги в программировании, одним из основных языков был ассемблер. В те времена подробные комментарии к каждой строке считались необходимостью — не столько по привычке, сколько по объективной сложности самого языка. Понять ассемблерный код без пояснений было практически невозможно.
С тех пор многое изменилось: большинство задач теперь решается с использованием языков высокого уровня. И вместе с этим возникает закономерный вопрос — действительно ли нам всё еще нужны комментарии? Или современный код может (и должен) объяснять себя сам?
Почему комментарии — не всегда добро
Комментарии изначально задумывались как способ сделать код понятнее. Но на практике они могут обернуться ловушкой.
Во-первых, они устаревают. Код меняется, бизнес-логика эволюционирует, а комментарии… забываются. И вот уже в тексте говорится одно, а код делает совершенно другое.
Иногда встречается еще одна форма «устаревания» комментариев — когда они теряют связь с тем кодом, который должны пояснять. Даже если сам комментарий остается актуальным по смыслу, проблема в том, что между ним и соответствующим фрагментом кода со временем могли появиться дополнительные строки. В итоге понять, к чему относится этот комментарий, становится настоящим испытанием: приходится прокручивать в уме несколько возможных связей, чтобы уловить его первоначальный смысл.
Во-вторых, они часто маскируют проблему. Вместо того чтобы улучшить читаемость, разработчик просто дописывает комментарий к непонятной строке. Это сигнал: коду не хватает выразительности.
Что такое самодокументируемый код
Самодокументируемый код — это стиль написания, при котором смысл заложен в самом коде, а не в сопровождающем тексте.
В чём его сила:
Говорящие имена. Переменные, функции, классы называют так, чтобы их назначение было очевидно без дополнительных пояснений.
Мелкие, логичные методы. Сложность разбивается на части, каждая из которых выполняет одну понятную задачу.
Минимум сюрпризов. Читая такой код, вы чувствуете себя уверенно. Он ведет за собой, как хорошо написанная инструкция.
Когда код говорит сам за себя: несколько примеров
💬 Было:
// Вычисляем общую стоимость заказа с учетом налогов и скидок
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() говорит сам за себя. Условие скрыто — но смысл раскрыт. Такой подход не только улучшает читаемость, но и упрощает повторное использование логики.
Что говорит об этом «Чистый код»
Роберт Мартин в своей книге «Чистый код» настойчиво подчеркивает: лучший комментарий — это тот, который не нужен. Если код требует пояснений — это сигнал, что его можно улучшить.
Он призывает:
Извлекать методы с понятными названиями.
Давать осмысленные имена переменным.
Избегать лишних комментариев.
Делать код максимально прозрачным и понятным.
Но не все так однозначно
Это не значит, что комментарии должны исчезнуть навсегда. Иногда они необходимы:
Чтобы объяснить почему сделано именно так, а не иначе.
Чтобы задокументировать сторонние ограничения.
Чтобы указать на временные решения или технический долг.
Но они должны быть исключением, а не правилом.
Заключение
Хороший код — как хороший текст: он читается легко, рассказывает о себе сам и не вызывает лишних вопросов. И хотя комментарии могут помочь, по-настоящему выразительный, самодокументируемый код делает их почти ненужными.
Следующий раз, когда потянетесь к //, спросите себя: а можно ли сделать код настолько понятным, чтобы он сам за себя говорил?
Скорее всего — можно.
