JavaScript アノテーション仕様パラメータ-フロントエンドQ&A-php.cn

ホームページ

ウェブフロントエンド

フロントエンドQ&A

JavaScript アノテーション仕様パラメータ

王林

May 17, 2023 pm 05:36 PM

JavaScript コメントの仕様とパラメーター

JavaScript コメントは、コードを読みやすく理解しやすくするための優れたプログラミング習慣です。コメントにより、コードの機能、目的、操作に関する詳細情報が提供されます。コメントは大規模な JavaScript アプリケーションを作成する場合に不可欠であり、コードの保守と改善が容易になります。この記事では、便利で効果的なコードコメントを作成するのに役立ついくつかのベストプラクティスについて説明します。

コメントの種類

JavaScript は、単一行コメントと複数行コメントという 2 つの異なるタイプのコメントをサポートしています。

単一行のコメントは、コードのブロックを一時的に無効にしたり、開発者がコードを覚えやすくしたりする目的でよく使用されます。単一行コメントでは、行の先頭に 2 つのスラッシュ「//」を使用してコード行をコメントアウトできます。

例:

// var x = 1;

ログイン後にコピー

複数行のコメントは通常、コードブロックを詳細に説明したり、使用方法を説明したりするために使用されます。複数行のコメントでは、先頭にスラッシュとアスタリスクの記号「/」を使用し、最後にアスタリスクとスラッシュの記号「/」を使用できます。

例:

/*
This function calculates the sum of two numbers.
@param {number} num1 - The first number.
@param {number} num2 - The second number.
@return {number} The sum of num1 and num2.
*/
function calculateSum(num1, num2) {
  return num1 + num2;
}

ログイン後にコピー

コメントの場所

一般に、コメントはできる限りコードブロックの先頭近くに配置する必要があります。関数またはメソッドにパラメータがある場合は、関数またはメソッドの先頭でパラメータをコメント化する必要があります。パラメーターの注釈は、パラメーターの期待値とタイプに関する情報を提供します。これはユーザーにとって非常に重要です。

例:

/**
 * 计算两个数字的和
 *
 * @param {number} a - 第一个数字
 * @param {number} b - 第二个数字
 * @returns {number} - a 和 b 的和
 */
function sum(a, b) {
  return a + b;
}

ログイン後にコピー

オブジェクトまたはクラスでは、コメントをプロパティおよびメソッド定義の前に配置する必要があります。

例:

/**
 * User 类
 * @class
 */
class User {
  /**
   * User 对象的构造函数
   *
   * @param {string} name - 用户名
   * @param {string} email - 用户邮箱
   */
  constructor(name, email) {
    this.name = name;
    this.email = email;
  }

  /**
   * 获得用户名
   *
   * @returns {string} - 用户名
   */
  getName() {
    return this.name;
  }

  /**
   * 获得用户邮箱
   *
   * @returns {string} - 用户邮箱
   */
  getEmail() {
    return this.email;
  }
}

ログイン後にコピー

コメントでパラメータを使用する

パラメータコメントでは、関数またはメソッドのパラメータの種類と期待値を指定できます。これらのコメントは、開発者がコードをより速く理解し、より簡単に開発するのに役立ちます。

パラメータのコメントは通常、@param {type} name - description の形式を使用します。

例:

/**
 * 计算两个数字的和
 *
 * @param {number} num1 - 第一个数字
 * @param {number} num2 - 第二个数字
 * @returns {number} - num1 和 num2 的和
 */
function calculateSum(num1, num2) {
  return num1 + num2;
}

ログイン後にコピー

コードスニペットの例をコメントに含める

一般に、コードコメントには、開発者の理解を助けるサンプルコードスニペットをいくつか保持する必要があります。コーディングが速くなります。サンプルコードでは関数やメソッドの正しい使用方法を示すことができるため、ユーザーが使用方法を忘れた場合でも、コメントから例をすぐに見つけることができます。

例:

/**
 * 将给定的字符串翻转
 *
 * @param {string} str - 要翻转的字符串
 * @returns {string} - 翻转后的字符串
 *
 * @example
 *
 * // Returns "cba"
 * const reversed = reverse("abc");
 * console.log(reversed);
 */
function reverse(str) {
  return str.split("").reverse().join("");
}

ログイン後にコピー

コメント内での JSDoc タグの使用

JSDoc は、最も一般的に使用される JavaScript コメントタグの 1 つです。これはコードコメントの一般的な標準の 1 つであり、関数、メソッド、変数、プロパティ、クラスのコメントをマークするためによく使用されます。多くのコードエディターは JSDoc タグをサポートしており、ドキュメントの生成に使用できます。

JSDoc はタグの最初の文字として「@」記号を使用し、さまざまなパラメーターのタイプとオプションを受け入れます。たとえば、JSDoc では、@param タグを使用して関数またはメソッドのパラメータを指定できます。サンプルコードは次のとおりです。

/**
 * 计算两个数字的和
 *
 * @param {number} num1 - 第一个数字
 * @param {number} num2 - 第二个数字
 * @returns {number} - num1 和 num2 的和
 */
function calculateSum(num1, num2) {
  return num1 + num2;
}

ログイン後にコピー