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

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

В нашем обсуждении на этот раз мы увидим, насколько важно комментировать функцию, которую мы создали сами, конечно же, на JavaScript. Представьте, что у нас есть такая функция:

function setLocation(x, y) {
  window.location.href = `${x}://${y}`;
}

window.location.href = `${x}://${y}`;

Что такое объяснение аргументов `x`и `y`? будем ли мы заполнять `object`или `string`, может быть, мы можем заполнить какой-то специальный ввод? другой мы используем Typescript, механизм данных типа будет выполняться самим Typescript во время выполнения или, возможно, во время разработки , но как насчет того, чтобы мы использовали JavaScript?

Да, в JavaScript (JS) аргументы функции `setLocation`будут отображаться редактором IntelliSense , что `any`означает, что любые данные будут разрешены.

Как вы можете видеть, в основном здесь есть проблема двоих; Computer и Human , когда компьютер читает код, будет продолжать работать независимо от имени аргумента, которое мы установили, но как насчет Human ?

Создаваемую нами функцию будет сложно понять следующему разработчику (человеку), потому что, не зная, что отправить в `setLocation`функцию, другое дело, если мы оставим комментарий.

// args `x` with data type string, is a protocol
// args `y` with data type string, is a domain name
function setLocation(x, y) {
  window.location.href = `${x}://${y}`;
}

Попробуем прокомментировать созданную нами функцию, по стандарту JSDoc , изменим комментарий выше на что-то вроде этого

/**
 * A function that can be executed on address bar browser
 * @param {string} x a host url
 * @param {string} y a domain url
 */
function setLocation(x, y) {
  window.location.href = `${x}://${y}`;
}

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

Это очень полезно, особенно если у нас есть функция, в которую мы должны отправить объект данных в качестве параметра функции, например, у нас есть такая функция

/**
 * @param {object} fullName
 * @param {string} fullName.firstName your first name
 * @param {string} fullName.lastName your last name
 */
function overwriteData(fullName) {
  return {
    firstName: "Adib",
    lastName: "Firman",
    ...fullName
  };
}

Как и обычный IntelliSense подскажет, и вы знаете, что интереснее для этого подхода

На картинке выше мы будем вводить данные по инструкции от IntelliSense конечно же получим подсказку от нашего редактора, интересно, не так ли?

Следующий вопрос: должны ли мы комментировать все функции, которые мы создали? Конечно нет, пример такой функции

const sum = (firstNum, secondNum) => firstNum + secondNum;

Заключение

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

Но если вы чувствуете, что функцию нужно прокомментировать, это лучше, потому что ее будет легче поддерживать следующему разработчику (человеку).

Спасибо.