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

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

Очевидные комментарии

Не надо писать очевидные комментарии в коде:

// Обновляем состояние на успешное
setState({ success: true });

Человек, которые читает код должен из объектов, функций и переменных сам понять какую задачу решает тот или иной кусок кода. Такие комментарии только усложняют чтение и удлиняют код. В данном случае по названию метода и аргумента сразу становится понятно, что происходит.

Называйте правильно

Чтобы сократить число комментариев в коде пишите понятные названия методов, переменных или классов:

// Получение пользователя по его идентификатору
get(i: number) { ... }

Вместо комментария достаточно правильно назвать функцию и её аргумент:

getUserById(id: number) { ... }

Предметная область

Следует комментировать описания классов или интерфейсов, которые относятся к реальной предметной области, чтобы связать ваш код с бизнес терминами. Без них вы потом будете долго разбираться, что необходимо изменить, когда бизнес принесёт баг о том, что нет подписанта документа:

/* @summary Идентификатор подписанта докумена */
signerId: number

Так же это облегчит использование в коде, так как большинство IDE покажет теги JSDoc во всплывающей подсказке, а для новых разработчиков проложит мост между терминами в техническом задании и кодом, который предстоит модифицировать.

Контракты

Если вы описываете контракты на стыке между front и backend или микросервисами, то свойства передаваемого объекта лучше пояснять, если эту функцию не выполнять swagger. Так вы облегчите интеграцию между частями системы, особенно если команда не состоит из одного человека 🙂

export class ImageRequirement {
    /** @summary Формат изображения для генерации */
    @IsEnum(ImageType)
    format: ImageType;
}

Не очевидные вещи

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

/* На текущий момент мы по умолчанию ставим что
* все платежи проверены, пока в ТЗ (...) не внесен
* алгоритм валидации платежей */
getPayments(paymentId: number, isValidated: boolean = true) { ... }

Интеграции с внешними сервисами

Если ваш сервис интегрируется с внешними API, то все запросы и ответы лучше всего так же покрывать @summary для расшифровки, а то не все внешние сервисы имеют понятные контракты взаимодействия. Особенно стоит обратить внимание на числовые статусы, которые может вернуть сервис:

enum PayApiStatus {
    /** @summary если платёж принят, но не выполнен */
    Accepted = 1
}

TODO

Так же хорошо помечать в коде не доделанные места как для себя, так и для того, кто будет делать ревью этого кода. Есть так же куча плагинов, которые позволят быстро посмотреть все TODO в коде:

// TODO: Доделать часть отправки уведомления

Я например использую ToDo Tree.

Документация

Если вы пользуетесь генератором документации на основании кода, тогда вы можете дополнительно включать @summary или @returns для включения в доку:

/**
 * Генерация изображений
 * @summary
 * Метод позволяет получить нарезку изображений нужного формата jpg, png, webp с указанной шириной и высотой.
 * При генерации изображения сервис ориентируется на высоту как ограничивающий параметр.
 * @returns GenerateImages.Response - Те же требования в каждый из которых добавлено созданное изображение,
 * а так же исходное изображение. Если оно было трансформировано, то в данных к этому изображению
 * будут параметры изображения после трансформации.
 */
generateImages(...) { ... }

Доступные теги можно посмотреть в JSDoc. Но при этом не надо этим злоупотреблять. Ведь если вы пишете на TypeScript, то он уже за вас знает о всех типах и весь функционал JSDoc вам в реальности не нужен. Комментируйте только то, что действительно важно в документации.

Итог

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