May 22 at 12:11

Что такое комментарии, зачем они нужны и в каких случаях?

Medium

Invite pending

Комментарии в программировании — вещь простая, касающаяся стиля кода. В JavaScript это выглядит так:

// комментарий

На курсах или просто при чтении кода можно увидеть, как люди комментируют строчку. И вроде читаешь и думаешь: «Ага, вот так это работает, хорошо, буду знать!» Можно ставить комментарии под каждой строкой или перед ней.

Но потом кажется, будто этот «снег» накапливается, и читать становится тяжелее — именно из‑за комментариев, потому что они на каждой строке. Так точно делать не нужно!

Содержание:

Нужно ли использовать комментарии
Может ли типизация заменить комментарии и когда
Итог

1. Нужно ли использовать комментарии?

Они важны, особенно когда работаешь в команде.
Если ты делаешь маленький проект, например, простую страницу для новостного блога, отдаёшь её заказчику и знаешь, что больше к ней не вернёшься, то комментарии могут просто занять лишнее время.
А нужны ли они в таком случае? Было бы интересно узнать ваше мнение.

Когда проект становится масштабным — без комментариев не обойтись.
Добавляются функции, сторонние библиотеки (не Redux или MobX, а, допустим, какая‑то старая или маленькая библиотека). И в таком случае комментарии помогают, особенно при быстром онбординге нового сотрудника. Чтобы он не только услышал, как работает код, но и увидел — откуда «растут ноги» и как всё устроено.

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

Особенно полезно, когда речь идёт о таких вещах, как SSR и i18n. В Next.js постоянно выходят обновления, появляются новые подходы для языка без мигания, или для отключённого JS. Проще вернуться к комментарию, чем заново лезть в TypeScript‑библиотеки, читать документацию и вспоминать, как и почему это было сделано.

Пример:

// Отключаем автоматическую локализацию при SSR, // чтобы избежать мигания при загрузке страницы.

Пример комментария, который может оказаться лишним

Первый файл:

// functions.js

// ... другие функции

export const sumValues = (...numbers) => numbers.reduce((acc, item) => acc + item, 0)

У нас есть файл functions.js, в котором собраны функции, используемые в разных частях проекта.
Они написаны простым и понятным способом — по названиям уже можно догадаться, за что каждая отвечает.

Например, функция sumValues складывает переданные в неё значения и возвращает итоговую сумму.
Это понятно даже без комментариев — и именно поэтому здесь они не нужны.

Второй файл:

// shop.js

import { sumValues } from '@/global/functions'

// ...

const calculateTotal = (prices) => {
  return sumValues(...prices)
}

// ...

const result = calculateTotal(TotalProductsPrice)

console.log('Ваша сумма за товары:', result)

Снова: хочется ли сюда вставить комментарии? Возможно — нет.
Всё довольно прозрачно:

Мы импортируем функцию sumValues,
Передаём в неё массив цен,
Получаем итоговое значение,
И выводим его в консоль.

Без комментариев всё и так читается — и это хорошо.

Когда комментарии всё же нужны?

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

Чтобы такого не случалось, важно:

Давать переменным и функциям понятные названия,
Писать читаемый код,
Проводить качественное ревью перед публикацией.

Если код понятен и сам себя объясняет — это победа. Комментарии нужны только там, где без них действительно не обойтись.

Вывод:

Комментарии — вещь полезная, но не всегда обязательная.
Не стоит писать их просто потому, что «так принято».

Пишите чистый, читаемый и понятный код. Так вы сэкономите время себе и другим.
А если что‑то действительно сложно — вот тогда комментарий точно не будет лишним.

2. Может ли типизация заменить комментарии и когда?

Типизация в TypeScript — вещь очень полезная.
Сегодня без неё сложно представить серьёзную разработку, особенно если ты уже пришёл в JavaScript из других языков или просто настолько к ней привык, что даже простые функции покрываешь generic‑типами или хотя бы простыми аннотациями вроде : string.

Типизация отлично описывает:

какие данные мы хотим получить на входе,
и что ожидаем на выходе.

Пример 1:

// shop.ts

import { sumValues } from '@/global/functions'

const calculateTotal = <T extends number[]>(prices: T): number => {
  return sumValues(...prices)
}

const totalPrices: number[] = [100, 200, 300]

const result: number = calculateTotal(totalPrices)

console.log('Ваша сумма за товары:', result)

Согласитесь, как же удобно!
Мы сразу видим:

Название функции — calculateTotal,
Что она принимает — массив чисел,
Что возвращает — итоговую сумму как number.

Зачем здесь комментарии? Всё и так понятно из самой структуры.

Пример 2:

// shop.ts

import { sumValues } from '@/global/functions'

const total = <T extends number[]>(prices: T): number => {
  return sumValues(...prices)
}

const prices: number[] = [100, 200, 300]

const result: number = total(prices)

console.log('Ваша сумма за товары:', result)

Пример похожий. Да, можно сказать, что названия переменных тут менее выразительные (total, prices), но благодаря типизации всё равно понятно, что происходит. А если ещё и код отформатирован — то и подавно!

Когда комментарии всё же нужны (даже с типами)

Типизация отвечает на вопрос: «что?», но не всегда отвечает на вопрос: «зачем?» или «почему именно так?»

Пример 3:

// order.ts

/**

 * Сортируем заказы по приоритету клиента.
 * VIP-клиенты всегда идут первыми.
 
*/

export const sortOrders = (orders: Order[]): Order[] => {
  return orders.sort((a, b) => {
    if (a.vip && !b.vip) return -1
    if (!a.vip && b.vip) return 1
    return a.date.getTime() - b.date.getTime()
  })
}

Да, у нас есть тип Order, и, допустим, там описано:

type Order = {
  id: string
  date: Date
  vip: boolean
}

Но без комментария неочевидно, почему сортировка именно такая:

Почему vip идёт первым?
Почему сначала приоритет, а потом дата?

Вот в таких случаях комментарий играет важную роль.
Он поясняет бизнес‑логику или неочевидное поведение, которое из кода сразу не видно.

Вывод:

Типизация в TypeScript часто заменяет необходимость в комментариях — и это круто!
Но не стоит полностью отказываться от них.

Используйте комментарии, когда нужно объяснить почему вы что‑то делаете, а не просто что вы делаете.

3. Итог

Комментарии — это важная часть кода.
Они помогают понять, что делает код и почему именно так, а не иначе.

Типизация — тоже описание. Она показывает, что принимает и что возвращает функция или блок кода. Это тоже важно.
Но есть одно ключевое отличие:

Типизация объясняет «что», а комментарии — «почему».

Типы говорят нам:
«Вот здесь строка, вот тут число, а функция возвращает массив.»
Комментарии же добавляют контекст:
«Почему мы делаем сортировку именно так?»,
«Зачем здесь используется этот флаг?»,
«Почему нельзя просто передать null?»

Комментарии — это живой голос разработчика, который помогает другим (и себе через полгода) быстрее вникнуть в суть.
Типизация — это строгий язык для проверки кода. Полезный, но не всегда объясняющий.

Так что типизация не заменяет комментарии. Обе эти вещи важны и прекрасно дополняют друг друга.

Мой канал в Telegram: https://t.me/nickwhite_web

Там я выкладываю посты и новости по JavaScript и Web‑разработке.

Хаб по JavaScript: https://github.com/n1ckwhite/JavaScript‑Universe

Здесь вы найдёте:

Часто задаваемые вопросы на собеседованиях
Полезные задачи
Обучающие статьи по написанию скриптов

Буду всегда рад помочь и поделиться новостями! Спасибо за чтение 🙂

Hubs: