如何在JavaScript中写注释

介绍

在编程中，我们首先考虑的通常是机器——计算机如何读取和解释我们编写的代码。然而，考虑将阅读和使用代码的人也同样重要。无论您是与团队合作还是独自工作，您都需要学习为人类读者正确地注释和构建您的代码。

注释是程序源代码中被解释器忽略的注释，因此对代码的实际输出没有影响。注释对于解释代码正在或应该做什么的意图非常有帮助。

作为一名开发人员，深入研究由其他人编写的未正确注释的代码可能会令人沮丧，而且当您不再沉浸在程序的上下文中时，很容易忘记自己的代码的含义。尽早评论您的代码将在您的整个职业生涯中加强良好的编程习惯，以避免以后出现这些问题。

注释语法

让我们快速浏览一下两种不同类型的 JavaScript 注释语法。

单行注释用两个正斜杠书写（//）：

// This is a comment

JavaScript 将忽略紧跟 // 语法直到行尾的所有字符。

Block 注释，有时称为多行注释，由开始标记 (/*) 和结束标记 (*/) 编写。如果您了解 CSS，那么您已经熟悉块级注释。

/* This is
a comment */

上面代码块中开始和结束标记之间的所有内容都将被忽略。

单行和多行注释都写在它们被指定解释的代码之上，如“Hello, World!”中所示。例子：

你好.js

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

编写注释时，将它们缩进到与它们下面的代码相同的级别：

海洋.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());
}

请注意，注释与程序本身一样是代码的一部分。过时的评论可能比没有评论更有害，因此请记住定期维护和更新评论以及其他所有内容。

内联评论

当单行注释出现在代码行的末尾时，它们被称为 行内注释 。

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

内联注释可用于对小的、特定的内容片段进行快速注释。由于注释应该只与它所写的确切行相关，因此它是最明显的注释类型。

请记住，无法在一行中结束单行注释，因此请确保不要在 // 语法之后放置任何代码，如下例所示。

破碎的.js

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

尽管内联注释很有用，但应谨慎使用——被大量内联注释覆盖的代码很快就会变得混乱，因此难以阅读。

阻止评论

块级注释或多行注释是用于介绍和解释一段代码的长格式注释。通常这些类型的注释被放置在文件的顶部，或者在一个特别复杂的代码块之前。

问候.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();

您有时还可能会看到块注释语法的略微修改版本，它以 /** 开头，并在注释块的左侧包含星号。

海.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。

注释掉测试代码

注释还可用于快速轻松地阻止执行代码以进行测试和调试。这被称为“注释掉代码”。

如果您编写的某些代码存在错误，注释掉部分将阻止它们运行，并且有助于查明问题的根源。您也可以使用它在代码之间切换以测试不同的结果。

数学.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);

单行注释和块注释都可以用来注释掉代码，这取决于被切换部分的大小。

注意：注释掉代码只能在测试期间进行。不要在最终脚本中留下注释掉的代码片段。

在制定程序的逻辑时，注释掉代码可能会很有帮助，因为您可以确定错误在哪里或评估提供最多实用程序的代码行。

结论

JavaScript 代码由计算机解释，但总是会被其他程序员阅读，包括你未来的自己。花时间在复杂的代码部分留下适当的注释将在未来获得回报，使您和合作者更容易理解您编写的代码的意图。