TOC

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

Вступление

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

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

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

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

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

// This is a comment

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

КомментарииBlock, иногда называемые комментариямиmutli-line, записываются с открывающими тегами (/*) и закрывающими тегами (*/). Если вы знаете CSS, то вы уже знакомы с комментариями на уровне блоков. 

/* This is
a comment */

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

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

hello.js

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

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

ocean.js

// 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());
}

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

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

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

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

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

broken.js

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

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

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

greet.js

/* 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();

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

sea.js

/**
 * 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, вы будете стремиться ответить на намерение илиwhy за кодом, в отличие отhow илиwhat.

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

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

math.js

// 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);

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

[.note] #Note: Комментировать код следует только во время тестирования. Не оставляйте фрагменты закомментированного кода в окончательном скрипте.
#

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

Заключение

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

Related