ホーム>Web デザインのチュートリアル>JavaScript チュートリアル

コメント

著者：Eve Cole 更新時間：2025-01-06 09:34:18

「コード構造」の章から分かるように、コメントは//で始まる単一行と/* ... */の複数行にすることができます。

通常、コードがどのように機能するのか、なぜ機能するのかを説明するためにこれらを使用します。

コメントは一見すると明白かもしれませんが、プログラミングの初心者はコメントを誤って使用することがよくあります。

悪いコメント

初心者は「コード内で何が起こっているのか」を説明するためにコメントを使用する傾向があります。このような：

 // このコードは、このこと (...) とあのこと (...) を実行します。
// ...そして他に何があるかは誰にも分かりません...
とても;
複雑な;
コード;

しかし、優れたコードでは、そのような「説明」コメントの量は最小限でなければなりません。真剣に考えれば、コードがなくてもコードは簡単に理解できるはずです。

これには素晴らしいルールがあります。「コメントが必要なほどコードが不明確な場合は、代わりにコードを書き直す必要があるかもしれません」。

レシピ: 因数分解関数

以下のように、コード部分を関数に置き換えることが有益な場合があります。

関数 showPrimes(n) {
  次のプライム:
  for (let i = 2; i < n; i++) {

    // i が素数かどうかをチェックする
    for (j = 2; j < i; j++) {
      if (i % j == 0) nextPrime を続行します。
    }

    アラート(i);
  }
}

より良いバリアントでは、関数isPrime取り除いたものを使用します。

関数 showPrimes(n) {

  for (let i = 2; i < n; i++) {
    if (!isPrime(i)) 続行;

    アラート(i);
  }
}

関数 isPrime(n) {
  for (let i = 2; i < n; i++) {
    if (n % i == 0) は false を返します。
  }

  true を返します。
}

これでコードを簡単に理解できるようになりました。関数自体がコメントになります。このようなコードは、 自己記述的と呼ばれます。

レシピ: 関数を作成する

そして、次のような長い「コードシート」があるとします。

 // ここにウィスキーを追加します
for(let i = 0; i < 10; i++) {
  ドロップ = getWhiskey();
  匂い（滴）;
  add(ドロップ、ガラス);
}

// ここでジュースを追加します
for(let t = 0; t < 3; t++) {
  トマト = getTomato(); とします。
  調べる(トマト);
  ジュース = プレス(トマト);
  追加(ジュース、グラス);
}

// ...

次に、それを次のような関数にリファクタリングする方が良い可能性があります。

 addWhiskey(ガラス);
addJuice(グラス);

関数 addWhiskey(コンテナ) {
  for(let i = 0; i < 10; i++) {
    ドロップ = getWhiskey();
    //...
  }
}

関数 addJuice(コンテナ) {
  for(let t = 0; t < 3; t++) {
    トマト = getTomato(); とします。
    //...
  }
}

繰り返しになりますが、関数自体が何が起こっているかを示します。コメントすることは何もありません。また、コード構造は分割した方が優れています。すべての関数が何を行うか、何を受け取り、何を返すかは明らかです。

実際には、「説明的な」コメントを完全に避けることはできません。複雑なアルゴリズムがあります。また、最適化を目的とした賢い「微調整」もあります。ただし、一般的には、コードをシンプルかつ自己記述的に保つよう努めるべきです。

良いコメント

したがって、説明的なコメントは通常、悪いものです。どのコメントが良いですか？

  • アーキテクチャについて説明する

  • コンポーネントの概要、コンポーネントがどのように相互作用するか、さまざまな状況における制御フローとは何か、つまりコードの鳥瞰図を提供します。コードを説明する高レベルのアーキテクチャ図を構築するための特別な言語 UML があります。間違いなく勉強する価値があります。

  • 関数のパラメータと使用法を文書化する

  • 関数、使用法、パラメーター、戻り値を文書化するための特別な構文 JSDoc があります。

例えば：

 /**
 * x の n 乗を返します。
 *
 * @param {number} x 上げる数値。
 * @param {number} n 累乗は自然数でなければなりません。
 * @return {number} x の n 乗。
 */
関数 pow(x, n) {
  ...
}

このようなコメントにより、コードを調べなくても関数の目的を理解し、関数を正しい方法で使用できるようになります。

ちなみに、WebStorm のような多くのエディターもこれらを理解し、オートコンプリートや自動コード チェックを提供するために使用できます。

また、コメントから HTML ドキュメントを生成できる JSDoc 3 のようなツールもあります。 JSDoc の詳細については、https://jsdoc.app を参照してください。

  • なぜこの方法でタスクが解決されるのでしょうか?

  • 書かれていることは重要です。しかし、何が起こっているのかを理解するには、書かれていないことの方がさらに重要かもしれません。なぜこの方法でタスクが解決されるのでしょうか?コードからは答えが得られません。

    タスクを解決する方法がたくさんあるのに、なぜこれなのか?特にそれが最も明白なものではない場合。

    このようなコメントがないと、次のような状況が発生する可能性があります。

    1. あなた (またはあなたの同僚) が少し前に書いたコードを開いてみると、それが「最適ではない」ことがわかります。

    2. 「当時の私はなんて愚かだったのに、今はどれほど賢くなっているのだろう」と考え、「より明白で正しい」バリアントを使用して書き直します。

    3. …書き直したいという衝動はよかった。しかし、その過程で、「より明白な」解決策が実際には欠けていることがわかります。ずっと前にすでに試しているので、その理由さえおぼろげに覚えています。正しいバリアントに戻りましたが、時間の無駄でした。

    解決策を説明するコメントは非常に重要です。これらは、開発を正しい方法で継続するのに役立ちます。

  • コードの微妙な特徴はありますか?どこで使われているのでしょうか？

  • コードに微妙で直観に反した部分がある場合は、コメントする価値があります。

まとめ

優れた開発者の重要な兆候はコメントです。コメントの有無も同様です。

優れたコメントにより、コードを適切に保守し、遅れて戻ってコードをより効果的に使用できるようになります。

これにコメントしてください:

  • 全体的なアーキテクチャ、高レベルのビュー。

  • 関数の使用法。

  • 重要な解決策、特にすぐには分からない場合。

コメントは避けてください:

  • これにより、「コードがどのように機能するか」と「コードが何を行うか」がわかります。

  • これらを必要としないほど単純かつ自己記述的なコードにすることが不可能な場合にのみ、それらを含めてください。

コメントは、JSDoc3 などの自動ドキュメント ツールにも使用されます。コメントはコメントを読み取って、HTML ドキュメント (または別の形式のドキュメント) を生成します。

関連記事