Поиск по сайту:

Как писать комментарии в JavaScript

Введение

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

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

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

Синтаксис комментария

Давайте кратко рассмотрим два разных типа синтаксиса комментариев JavaScript.

Однострочные комментарии пишутся с двумя косыми чертами (//):

// This is a comment

Все символы, следующие за синтаксисом // до конца строки, будут игнорироваться JavaScript.

Блочные комментарии, иногда называемые многострочными комментариями, пишутся с открывающими тегами (/*) и закрывающими тегами (*/). Если вы знаете CSS, то вы уже знакомы с блочными комментариями.

/* This is
a comment */

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

Как однострочные, так и многострочные комментарии пишутся над кодом, для объяснения которого они предназначены, как показано в этом «Hello, World!» пример:

// Print "Hello, World!" to the console
console.log("Hello, World!");

При написании комментариев делайте отступ на том же уровне, что и код непосредственно под ними:

// Initialize a function
function alphabetizeOceans() {
	// Define oceans variable as a list of strings
	const oceans = ["Pacific", "Atlantic", "Indian", "Antarctic", "Arctic"];

	// Print alphabetized array to the console
	console.log(oceans.sort());
}

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

Встроенные комментарии

Однострочные комментарии называются встроенными комментариями, если они появляются в конце строки кода.

let x = 99;    // assign numerical value to x
let y = x + 2; // assign the sum of x + 2 to y

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

Помните, что невозможно закончить однострочный комментарий в строке, поэтому убедитесь, что после синтаксиса // не помещается какой-либо код, как показано в примере ниже.

for (let i = 0; i === 10; i++) // for loop that runs ten times {
	// Running this code results in a syntax error
}

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

Блокировать комментарии

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

/* Initialize and invoke a the greetUser function
to assign user's name to a constant and print out
a greeting. */

function greetUser() {
	const name = prompt("What is your name?");
	console.log("Hello ," + name + "! How are you?");
}

greetUser();

Вы также можете иногда увидеть слегка измененную версию синтаксиса блочного комментария, которая начинается с /** и включает звездочки в левой части блока комментариев.

/**
 * Initialize constant with an array of strings.
 * Loop through each item in the array and print
 * it to the console.
 */

const seaCreatures = ["Shark", "Fish", "Octopus"];

for (const seaCreature of seaCreatures) {
  console.log(seaCreature);
}

Иногда этот тип комментариев также включает сведения о программном файле, включая имя сценария, версию и автора.

Если вы новичок в JavaScript, вы можете написать столько, сколько необходимо, чтобы изучить и понять код, который вы пишете. По мере того, как вы становитесь разработчиком JavaScript, вы будете искать ответ на намерение или почему код, а не как или что.

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

Комментарии также можно использовать для быстрого и простого предотвращения выполнения кода в целях тестирования и отладки. Это называется «комментированием кода».

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

// Function to add two numbers
function addTwoNumbers(x, y) {
  let sum = x + y;
  return sum;
}

// Function to multiply two numbers
function multiplyTwoNumbers(x, y) {
  let product = x * y;
  return product;
}

/* In this example, we're commenting out the addTwoNumbers
function, therefore preventing it from executing. Only the
multiplyTwoNumbers function will run */

// addTwoNumbers(3, 5);
multiplyTwoNumbers(5, 9);

Для комментирования кода можно использовать как однострочные, так и блочные комментарии, в зависимости от размера переключаемого раздела.

Примечание. Комментировать код следует только в целях тестирования. Не оставляйте фрагменты закомментированного кода в окончательном сценарии.

При разработке логики программы комментирование кода может оказаться полезным, поскольку вы определяете, где находятся ошибки, или оцениваете наиболее полезные строки кода.

Заключение

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