Антон Ларичев
Конечно, когда ты пишешь код, необходимо писать его максимально понятно, называя корректно методы и переменные и декомпозируя сложные функции. Но сейчас пост не об этом, а о комментариях в коде. Когда их писать надо, а когда нет.
Очевидные комментарии
Не надо писать очевидные комментарии в коде:
// Обновляем состояние на успешное
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 вам в реальности не нужен. Комментируйте только то, что действительно важно в документации.
Итог
Не бойтесь пользоваться комментариями, но делайте это только тогда, когда это действительно принесёт пользу вам и вашим коллегам. Ни кто не отменял, что хорошо написанный код - сам по себе понятный код.
Комментарии
0