JavaScriptでコメントを書く方法

前書き

プログラミングでは、通常、最初に考慮すべきことはマシンです。つまり、コンピューターが記述するコードを読み取り、解釈する方法です。 ただし、コードを読んで作業する人を考慮することも同様に重要です。 チームで作業している場合でも、自分で作業している場合でも、コードを適切にコメントし、人間の読者向けに構造化することを学ぶ必要があります。

コメントは、プログラムのソースコード内の注釈であり、インタープリターによって無視されるため、コードの実際の出力には影響しません。 コメントは、コードが何をしているのか、何をすべきなのかを説明するのに非常に役立ちます。

開発者として、適切にコメントされていない他の誰かによって書かれたコードを詳しく調べるのはイライラする可能性があります。また、プログラムのコンテキストに没頭していると、自分のコードが何を意味していたかを非常に簡単に忘れてしまいます。 早い段階でコードにコメントを付けると、キャリア全体で優れたプログラミング習慣が強化され、後でこれらの問題を回避できます。

JavaScriptの2種類のコメント構文を簡単に見てみましょう。

*単一行*コメントは、2つのスラッシュ( + // +)で記述されます:

// This is a comment

行末まで「+ // +」構文の直後にあるすべての文字はJavaScriptによって無視されます。

*ブロック*コメントは、*複数行*コメントとも呼ばれ、開始タグ( + / * +)および終了タグ( + * / +)で記述されます。 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());
}

コメントは、プログラム自体と同じくらいコードの一部であることに注意してください。 期限切れのコメントは、コメントがまったくないというよりも不利な場合があります。そのため、他のすべてのコメントとともに定期的にコメントを維持および更新することを忘れないでください。

単一行コメントは、コード行の最後に表示される場合、「インラインコメント」と呼ばれます。

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

インラインコメントは、コンテンツの小さな特定のスニペットにすばやく注釈を付けるために使用できます。 コメントは、記述されている正確な行にのみ関連する必要があるため、最も明白なタイプのコメントです。

1行のコメントを1行で終了する方法はないので、以下の例に示すように、 `+ // +`構文の後にコードを置かないようにしてください。

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開発者として進むにつれて、_how_や_what_ではなく、意図、またはコードの背後にある_why_に答えようとするでしょう。

また、コメントを使用して、テストやデバッグの目的でコードの実行を迅速かつ簡単に防ぐことができます。 これを「コードのコメントアウト」と呼びます。

記述したコードにエラーがある場合、セクションをコメントアウトすると実行できなくなり、問題の原因を特定するのに役立ちます。 また、異なる結果をテストするためにコードを切り替えるためにも使用できます。

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

切り替えられるセクションのサイズに応じて、単一行コメントとブロックコメントの両方を使用してコードをコメントアウトできます。

プログラムのロジックを処理するとき、バグの場所を特定したり、最も有用なコード行を評価したりするときに、コードをコメントアウトすると役立つことがわかります。

結論

JavaScriptコードはコンピューターによって解釈されますが、将来の自分を含む他のプログラマーによって常に読み取られます。 時間をかけてコードの複雑なセクションに適切な注釈を残すことは、将来的に利益をもたらし、あなたと協力者があなたが書いたコードの意図を理解しやすくします。