Комментарии: когда они помогают, а когда вредят

Комментарии - это как специи. Чуть-чуть - вкусно. Перебор - невозможно есть.

Главная проблема комментариев - они устаревают. Код меняется, комментарий остаётся. Через месяц он врёт. Через полгода - активно мешает.

Когда комментарии полезны

  • объясняют почему, а не что
  • предупреждают о неочевидном решении
  • дают ссылку на баг/тикет/RFC
  • описывают публичный API (godoc)

Когда комментарии вредят

  • описывают что делает код (это видно из кода)
  • устарели и врут
  • закомментированный код вместо удаления
  • «разделители» вместо функций

Плохие комментарии: примеры

// увеличиваем i на 1
i = i + 1

// получаем пользователя
user, err := repo.GetUser(ctx, id)

// цикл по элементам
for _, item := range items {
    process(item)
}
<?php
declare(strict_types=1);

// увеличиваем $i на 1
$i = $i + 1;

// получаем пользователя
$user = $repo->getUser($id);

// цикл по элементам
foreach ($items as $item) {
    process($item);
}
# увеличиваем i на 1
i = i + 1

# получаем пользователя
user = repo.get_user(user_id)

# цикл по элементам
for item in items:
    process(item)

Все три комментария не несут информации - они повторяют код. Удали их, и ничего не потеряется.

Хорошие комментарии: примеры

// Временный костыль: внешний сервис иногда возвращает дубликаты,
// поэтому фильтруем по id. Убрать после FIX-123.
items = dedupe(items)

// Порядок вызовов важен: сначала кэш, потом БД.
// Без кэша БД не выдерживает пиковую нагрузку (см. INC-42).
// Ловушка: при одновременных промахах в БД уйдёт несколько
// одинаковых запросов - если это станет проблемой, нужен singleflight.
cached := cache.Get(key)
if cached == nil {
    cached = db.Get(key)
    cache.Set(key, cached)
}

// RFC 7519, 4.1.4: токен нельзя принимать в момент exp и позже
if !time.Now().Before(claims.ExpiresAt) {
    return ErrTokenExpired
}
<?php
declare(strict_types=1);

// Временный костыль: внешний сервис иногда возвращает дубликаты,
// поэтому фильтруем по id. Убрать после FIX-123.
$items = dedupe($items);

// Порядок вызовов важен: сначала кэш, потом БД.
// Без кэша БД не выдерживает пиковую нагрузку (см. INC-42).
// Ловушка: при одновременных промахах в БД уйдёт несколько
// одинаковых запросов - если это станет проблемой, нужна блокировка на ключ.
$cached = $cache->get($key);
if ($cached === null) {
    $cached = $db->get($key);
    $cache->set($key, $cached);
}

// RFC 7519, 4.1.4: токен нельзя принимать в момент exp и позже
if ($claims->expiresAt <= new DateTimeImmutable()) {
    throw new TokenExpiredException();
}
from datetime import datetime, timezone

# Временный костыль: внешний сервис иногда возвращает дубликаты,
# поэтому фильтруем по id. Убрать после FIX-123.
items = dedupe(items)

# Порядок вызовов важен: сначала кэш, потом БД.
# Без кэша БД не выдерживает пиковую нагрузку (см. INC-42).
# Ловушка: при одновременных промахах в БД уйдёт несколько
# одинаковых запросов - если это станет проблемой, нужна блокировка на ключ.
cached = cache.get(key)
if cached is None:
    cached = db.get(key)
    cache.set(key, cached)

# RFC 7519, 4.1.4: токен нельзя принимать в момент exp и позже
if claims.expires_at <= datetime.now(timezone.utc):
    raise TokenExpiredError()

Хороший комментарий отвечает на вопрос «почему так, а не иначе?» или предупреждает о ловушке.

ℹ️ Лучший комментарий - это хорошее имя

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

Godoc: комментарии как документация

В Go комментарии к exported-символам - это документация. Они отображаются в go doc и на pkg.go.dev:

// UserRepo provides access to user storage.
// It handles database operations and caching.
type UserRepo struct { ... }

// GetByID returns a user by their unique identifier.
// Returns ErrNotFound if the user does not exist.
func (r *UserRepo) GetByID(ctx context.Context, id int) (*User, error) {

В PHP роль godoc выполняет PHPDoc - блочные комментарии /** ... */ с тегами. Их читает IDE для автодополнения, PHPStan для статического анализа, OpenAPI-генераторы для документации:

<?php
declare(strict_types=1);

/**
 * Хранилище пользователей с кешем и БД.
 *
 * @see UserRepositoryInterface
 */
final readonly class UserRepository
{
    /**
     * Возвращает пользователя по уникальному идентификатору.
     *
     * @param non-empty-string $id внешний UUID пользователя
     *
     * @throws UserNotFoundException если пользователя не существует
     * @throws RuntimeException     при ошибке сети с БД
     *
     * @deprecated since 2.5, use findById() instead
     */
    public function getById(string $id): User
    {
        // ...
    }
}

Роль godoc выполняют docstrings - строки в тройных кавычках сразу после def/class. Их показывает help(), читает IDE для подсказок, а Sphinx/MkDocs собирает в документацию:

class UserRepo:
    """Хранилище пользователей с кешем и БД.

    См. также: UserRepositoryProtocol.
    """

    def get_by_id(self, user_id: int) -> User:
        """Возвращает пользователя по уникальному идентификатору.

        Args:
            user_id: внутренний идентификатор пользователя.

        Raises:
            UserNotFoundError: если пользователя не существует.
            RuntimeError: при ошибке сети с БД.

        .. deprecated:: 2.5
            Используй find_by_id().
        """
        ...

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

Правило                      Go (godoc)
───────────────────────────  ──────────────────────────────
Описание поведения           // GetByID returns the user...
Ошибки явно                  // Returns ErrNotFound if...
Депрекация                   // Deprecated: use FindByID.
Ссылки                       [pkg.Name], [текст]: URL

Комментарий начинается с имени символа и пишется полным предложением.

Правило                      PHPDoc
───────────────────────────  ──────────────────────────────
Описание поведения           «Возвращает пользователя»
Ошибки явно                  @throws UserNotFoundException
Точные типы для PHPStan      @param non-empty-string $id
Депрекация                   @deprecated since 2.5
Ссылки                       @see, @link

Дополнительные теги PHPStan/Psalm: @param array{id: int, name: string} $data (shape types), @return list<User> (numeric arrays), @template T (generics). Это даёт строгую типизацию без рантайма. Отдельный случай - @method и @property: без них IDE и статический анализатор слепнут на классах с магическими методами, где объявленного метода физически нет, а вызов работает.

Правило                      Docstring (Google style)
───────────────────────────  ──────────────────────────────
Описание поведения           первая строка - что делает функция
Ошибки явно                  раздел Raises:
Аргументы                    раздел Args:
Депрекация                   .. deprecated:: 2.5

Типы пишут в аннотациях сигнатуры, а не в docstring: их проверяет mypy, а дублировать незачем.

⚠️ Не пиши godoc для unexported

Комментарии к приватным функциям пишутся по необходимости (когда есть «почему»). Godoc-стиль нужен только для exported-символов - именно они формируют публичный API пакета.

Закомментированный код - удаляй

// Плохо: мёртвый код, который «может пригодиться»
func ProcessOrder(order Order) error {
    // oldPrice := calculateOldPrice(order)
    // if oldPrice > 0 {
    //     applyDiscount(order, oldPrice)
    // }
    newPrice := calculatePrice(order)
    return charge(order, newPrice)
}

// Хорошо: удали. Git помнит всё.
func ProcessOrder(order Order) error {
    price := calculatePrice(order)
    return charge(order, price)
}
<?php
declare(strict_types=1);

// Плохо: мёртвый код, который «может пригодиться»
final class OrderProcessor
{
    public function process(Order $order): void
    {
        // $oldPrice = $this->calculateOldPrice($order);
        // if ($oldPrice > 0) {
        //     $this->applyDiscount($order, $oldPrice);
        // }
        $newPrice = $this->calculatePrice($order);
        $this->charge($order, $newPrice);
    }
}
<?php
declare(strict_types=1);

// Хорошо: удали. Git помнит всё.
final class OrderProcessor
{
    public function process(Order $order): void
    {
        $price = $this->calculatePrice($order);
        $this->charge($order, $price);
    }
}
# Плохо: мёртвый код, который «может пригодиться»
def process_order(order: Order) -> None:
    # old_price = calculate_old_price(order)
    # if old_price > 0:
    #     apply_discount(order, old_price)
    new_price = calculate_price(order)
    charge(order, new_price)


# Хорошо: удали. Git помнит всё.
def process_order(order: Order) -> None:
    price = calculate_price(order)
    charge(order, price)

Закомментированный код - это шум. Он заставляет каждого читателя задуматься: «Это важно? Это нужно раскомментировать? Почему это здесь?». Git хранит историю - если код понадобится, его находят через log, blame и bisect, а не через закомментированный блок в рабочем файле.

TODO и FIXME: когда допустимо

// TODO(jdoe): заменить на batch-insert, тикет SHOP-123
for _, user := range users {
    if err := repo.Create(ctx, user); err != nil {
        return err
    }
}

// FIXME: race condition при конкурентных запросах, нужен mutex
counter++
<?php
declare(strict_types=1);

// TODO(jdoe): заменить на batch-insert, тикет SHOP-123
foreach ($users as $user) {
    $repo->create($user);
}

// FIXME: race condition при конкурентных запросах, нужен distributed lock
$counter++;
# TODO(jdoe): заменить на batch-insert, тикет SHOP-123
for user in users:
    repo.create(user)

# FIXME: race condition при конкурентных запросах, нужен threading.Lock
counter += 1

Правила для TODO/FIXME:

Хорошо                               Плохо
──────────────────────────────────   ──────────────────────────────
TODO(автор): конкретное действие     TODO: fix this
TODO + ссылка на тикет               TODO: сделать лучше
FIXME с описанием бага               FIXME (без объяснения)

Комментарии-разделители → Extract Method

Если ты пишешь // --- шаг 1 --- - это сигнал, что нужна маленькая функция:

// Плохо: комментарии-разделители
func HandleRequest(r *http.Request) error {
    // --- parse input ---
    var input RequestInput
    json.NewDecoder(r.Body).Decode(&input)

    // --- validate ---
    if input.Name == "" { return ErrNoName }

    // --- save ---
    db.Create(&input)
    return nil
}

// Хорошо: функции вместо комментариев
func HandleRequest(r *http.Request) error {
    input, err := parseInput(r)
    if err != nil {
        return err
    }
    if err := validateInput(input); err != nil {
        return err
    }
    return saveInput(input)
}
<?php
declare(strict_types=1);

// Плохо: комментарии-разделители
final class RequestHandler
{
    public function handle(Request $request): void
    {
        // --- parse input ---
        $input = json_decode($request->getContent(), associative: true, flags: JSON_THROW_ON_ERROR);

        // --- validate ---
        if (($input['name'] ?? '') === '') {
            throw new DomainException('name is required');
        }

        // --- save ---
        $this->db->create($input);
    }
}
<?php
declare(strict_types=1);

// Хорошо: методы вместо комментариев
final class RequestHandler
{
    public function handle(Request $request): void
    {
        $input = $this->parseInput($request);
        $this->validateInput($input);
        $this->saveInput($input);
    }
}
import json


# Плохо: комментарии-разделители
def handle_request(request: Request) -> None:
    # --- parse input ---
    data = json.loads(request.body)

    # --- validate ---
    if not data.get("name"):
        raise ValueError("name is required")

    # --- save ---
    db.create(data)


# Хорошо: функции вместо комментариев
def handle_request(request: Request) -> None:
    data = parse_input(request)
    validate_input(data)
    save_input(data)

Названия функций - это самодокументирующиеся комментарии, которые компилятор проверяет. Сама механика такого выноса называется Extract Function (в первом издании книги Фаулера «Рефакторинг» - Extract Method, это одно и то же), и делать её нужно маленькими безопасными шагами - алгоритм в уроке про рефакторинг.

Мини-задание

  • Найди 3 бесполезных комментария в проекте (описывают «что», а не «почему»)
  • Удали их или замени хорошими именами функций/переменных
  • Проверь godoc для exported-символов: начинаются ли с имени?
  • Найди и удали закомментированный код - Git всё помнит

Зарегистрируйтесь бесплатно, чтобы пройти квиз, вести прогресс.