Комментарии: когда они помогают, а когда вредят
Комментарии - это как специи. Чуть-чуть - вкусно. Перебор - невозможно есть.
Главная проблема комментариев - они устаревают. Код меняется, комментарий остаётся. Через месяц он врёт. Через полгода - активно мешает.
Когда комментарии полезны
- объясняют почему, а не что
- предупреждают о неочевидном решении
- дают ссылку на баг/тикет/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 всё помнит