Kode debug tanpa komentar seperti menjadi detektif yang mencoba memecahkan kejahatan, tetapi satu-satunya saksi berbicara dalam bahasa asing, dan ada beberapa orang (klien) berpengaruh yang berusaha menyelesaikan kasus kemarin.

sumber gambar — Dua Pria Melihat Laptop · Foto Stok Gratis (pexels.com)

Perkenalan

Menambahkan komentar kode penting karena beberapa alasan:

1. Keterbacaan kode. Komentar membantu developer memahami tujuan di balik kode dengan menjelaskannya dalam bahasa sederhana, membuatnya lebih mudah dibaca dan dimodifikasi.

2. Pemeliharaan. Komentar membantu Anda mengingat tujuan kode Anda, membuatnya lebih mudah untuk dipelihara dan diperbarui di masa mendatang tanpa menyebabkan masalah secara tidak sengaja.

3. Kolaborasi. Komentar mencegah kesalahan dan salah tafsir dalam proyek kolaboratif dengan menyediakan konteks untuk perubahan kode, memastikan semua orang memiliki pemahaman yang sama.

4. Dokumentasi. Komentar kode memberikan kejelasan tentang tujuan dan fungsionalitas, memastikan kepatuhan dengan standar industri dan praktik terbaik. Mereka membuat kode lebih mudah dibaca, dipelihara, dan lebih mudah untuk dikerjakan, seperti panduan instruksi LEGO dalam membangun satu set.

Dengan meluangkan waktu untuk menambahkan komentar yang bermakna dan akurat ke dalam kode, pengembang dapat meningkatkan kualitas keseluruhan dan pemeliharaan proyek mereka.

Model Mental untuk Menambahkan Komentar ke Kode

Sebelum menulis komentar di sekitar sepotong kode, penting untuk memperjelas maksud melakukannya. Komentar kode adalah mekanisme komunikasi yang harus mengomunikasikan aspek kode berikut:

1. Tujuan. Jelaskan tujuan kode, masalah apa yang dipecahkannya dan mengapa kode itu ada.

2. Masukan. Tentukan input yang diperlukan oleh kode, termasuk jenisnya, nilai yang diharapkan, dan apakah itu opsional atau wajib.

3. Keluaran. Tentukan keluaran yang dihasilkan oleh kode, termasuk jenisnya dan detail yang relevan.

4. Penggunaan. Berikan contoh cara menggunakan kode, termasuk cuplikan kode yang relevan.

5. Menghubungkan. Tambahkan tautan ke kode terkait dan sumber daya eksternal.

6. Praktik terbaik. Sorot semua praktik terbaik atau gotcha yang terkait dengan kode.

Dengan mengikuti model mental yang tepat, developer dapat memastikan bahwa kode mereka terdokumentasi dengan baik, mudah dipahami, dan dapat dipelihara dari waktu ke waktu.

Konsistensi dan Standardisasi

Sangat penting untuk menjaga konsistensi dalam pemformatan dan gaya komentar di seluruh basis kode. Menggunakan alat seperti JS Doc (dokumentasi JavaScript), yang merupakan kumpulan standar dokumentasi dan alat untuk mendokumentasikan kode JavaScript, adalah pilihan yang baik.

Berikut ini adalah beberapa fitur JS Doc:

• Ini menggunakan tag untuk menangkap informasi tentang struktur kode, fungsi, parameter, nilai pengembalian, dan detail lainnya untuk membuat referensi yang dapat dibaca manusia untuk pengembang lain.
• Tag JS Doc dimulai dengan @simbol, diikuti dengan nama tag dan informasi yang relevan. Misalnya, paramtag digunakan untuk mendeskripsikan parameter fungsi, sedangkan returnstag digunakan untuk mendeskripsikan nilai kembalian suatu fungsi.
• Itu dapat menghasilkan dokumentasi dalam HTML atau format lain dari komentar sebaris dalam kode sumber.

function factorial(n) {
  if (typeof n !== "number") {
    throw new TypeError("Input must be a number");
  }
  if (n === 0) {
    return 1;
  }
  return n * factorial(n - 1);
}

function factorialWithCallback(n, callback) {
  try {
    const result = {
      input: n,
      output: factorial(n),
    };
    callback(null, result);
  } catch (error) {
    callback(error);
  }
}

Tag Dokumen JS yang umum digunakan

Mari kita lihat beberapa tag JS Doc yang cukup sering digunakan.

• @todo

/**
 * @todo Add details about the factorial calculation and edge cases.
 */
function factorial(n) {
  if (typeof n !== "number") {
    throw new TypeError("Input must be a number");
  }
  if (n === 0) {
    return 1;
  }
  return n * factorial(n - 1);
}

/**
 * @todo Add an example usage of the callback function.
 */
function factorialWithCallback(n, callback) {
  try {
    const result = {
      input: n,
      output: factorial(n),
    };
    callback(null, result);
  } catch (error) {
    callback(error);
  }
}

Langkah pertama adalah menjelaskan apa yang dilakukan kode. @descriptiontag digunakan untuk memberikan deskripsi rinci tentang fungsi, objek, atau properti. Mari kita lihat bagaimana tampilan kode setelah menambahkan tag ini.

/**
 * @description A function that calculates the factorial of a number using recursion.
 */
function factorial(n) {
  if (typeof n !== "number") {
    throw new TypeError("Input must be a number");
  }
  if (n === 0) {
    return 1;
  }
  return n * factorial(n - 1);
}

/**
 * @description A version of the factorial function that returns the result via a callback.
 */
function factorialWithCallback(n, callback) {
  try {
    const result = {
      input: n,
      output: factorial(n),
    };
    callback(null, result);
  } catch (error) {
    callback(error);
  }
}

Di sinilah bagian di mana diberitahu input apa yang diambil kode. @paramtag digunakan untuk mendeskripsikan parameter suatu fungsi. Menambahkannya ke contoh membuat kode terlihat seperti ini:

/**
 * @description A function that calculates the factorial of a number using recursion.
 * 
 * @param {number} n - The number for which to calculate the factorial.
 */
function factorial(n) {
  if (typeof n !== "number") {
    throw new TypeError("Input must be a number");
  }
  if (n === 0) {
    return 1;
  }
  return n * factorial(n - 1);
}

/**
 * @description A version of the factorial function that returns the result via a callback.
 * 
 * @param {number} n - The number for which to calculate the factorial.
 * @param {function} callback - The function to call with the result of the calculation.
 */
function factorialWithCallback(n, callback) {
  try {
    const result = {
      input: n,
      output: factorial(n),
    };
    callback(null, result);
  } catch (error) {
    callback(error);
  }
}

Sejauh ini kita tahu apa fungsinya, dan input yang dibutuhkan. Berikutnya datang menjelaskan nilai kembalian dari suatu fungsi. Menambahkan @returnske contoh membuat kode terlihat seperti ini:

/**
 * @description A function that calculates the factorial of a number using recursion.
 * 
 * @param {number} n - The number for which to calculate the factorial.
 * 
 * @returns {number} The factorial of `n`.
 */
function factorial(n) {
  if (typeof n !== "number") {
    throw new TypeError("Input must be a number");
  }
  if (n === 0) {
    return 1;
  }
  return n * factorial(n - 1);
}

/**
 * @description A version of the factorial function that returns the result via a callback.
 * 
 * @param {number} n - The number for which to calculate the factorial.
 * @param {function} callback - The function to call with the result of the calculation.
 * 
 * @returns {void}
 */
function factorialWithCallback(n, callback) {
  try {
    const result = {
      input: n,
      output: factorial(n),
    };
    callback(null, result);
  } catch (error) {
    callback(error);
  }
}

Akan ada saatnya ketika fungsi mengalami kesalahan dan tidak dapat memberikan hasil yang diinginkan. @throwsmembantu dalam mendokumentasikan skenario tersebut. Menambahkan @throwske contoh membuat kode terlihat seperti ini:

/**
 * @description A function that calculates the factorial of a number using recursion.
 * 
 * @param {number} n - The number for which to calculate the factorial.
 * 
 * @returns {number} The factorial of `n`.
 * 
 * @throws {TypeError} If the input is not a number.
 */
function factorial(n) {
  if (typeof n !== "number") {
    throw new TypeError("Input must be a number");
  }
  if (n === 0) {
    return 1;
  }
  return n * factorial(n - 1);
}

/**
 * @description A version of the factorial function that returns the result via a callback.
 * 
 * @param {number} n - The number for which to calculate the factorial.
 * @param {function} callback - The function to call with the result of the calculation.
 * 
 * @returns {void}
 */
function factorialWithCallback(n, callback) {
  try {
    const result = {
      input: n,
      output: factorial(n),
    };
    callback(null, result);
  } catch (error) {
    callback(error);
  }
}

Kadang-kadang, konsumen atau pemanggil kode tidak tertarik dengan detail implementasi tingkat rendah, dan khawatir tentang pemanggilan dan mendapatkan hasil yang diharapkan. @exampletag digunakan untuk memberikan contoh cara menggunakan fungsi atau objek. Menambahkan @exampleke contoh membuat kode terlihat seperti ini:

/**
 * @description A function that calculates the factorial of a number using recursion.
 * 
 * @param {number} n - The number for which to calculate the factorial.
 * 
 * @returns {number} The factorial of `n`.
 * 
 * @throws {TypeError} If the input is not a number.
 * 
 * @example
 * factorial(5);
 * // returns 120
 */
function factorial(n) {
  if (typeof n !== "number") {
    throw new TypeError("Input must be a number");
  }
  if (n === 0) {
    return 1;
  }
  return n * factorial(n - 1);
}

/**
 * @description A version of the factorial function that returns the result via a callback.
 * 
 * @param {number} n - The number for which to calculate the factorial.
 * @param {function} callback - The function to call with the result of the calculation.
 * 
 * @returns {void}
 * 
 * @example
 * factorialWithCallback(5, (error, result) => {
 *   if (error) {
 *     console.error(error);
 *   } else {
 *     console.log(result);
 *   }
 * });
 * // logs { input: 5, output: 120 }
 */
function factorialWithCallback(n, callback) {
  try {
    const result = {
      input: n,
      output: factorial(n),
    };
    callback(null, result);
  } catch (error) {
    callback(error);
  }
}

Tag JSDoc @typedigunakan untuk menentukan jenis variabel, fungsi, atau ekspresi. Ini memberikan informasi tambahan tentang jenis entitas yang didokumentasikan dan membantu keterbacaan dan pemeliharaan kode.

Tag @typedefJSDoc, di sisi lain, digunakan untuk menentukan jenis kustom. Ini dapat berguna dalam proyek kompleks di mana Anda memiliki struktur atau tipe data khusus yang perlu didokumentasikan. Jenis khusus yang ditentukan dengan @typedefkemudian dapat direferensikan dengan @typetag di bagian lain dari kode.

Intinya, @typedefdigunakan untuk mendefinisikan tipe kustom, sedangkan @typedigunakan untuk menentukan tipe entitas.

Tag JSDoc @propertydigunakan untuk mendokumentasikan properti dari suatu objek atau kelas. Ini biasanya digunakan bersamaan dengan @typedefuntuk mendokumentasikan struktur objek atau kelas. Tag @propertymenentukan nama dan jenis properti, serta deskripsi tujuannya.

Menambahkan @type, @typedef, dan @propertyke contoh membuat kode terlihat seperti ini:

/**
 * @typedef {Object} FactorialResult
 * 
 * @property {number} input - The input to the factorial function.
 * @property {number} output - The output of the factorial function.
 */

/**
 * @description A function that calculates the factorial of a number using recursion.
 * 
 * @param {number} n - The number for which to calculate the factorial.
 * 
 * @returns {number} The factorial of `n`.
 * 
 * @throws {TypeError} If the input is not a number.
 * 
 * @example
 * factorial(5);
 * // returns 120
 */
function factorial(n) {
  if (typeof n !== "number") {
    throw new TypeError("Input must be a number");
  }
  if (n === 0) {
    return 1;
  }
  return n * factorial(n - 1);
}

/**
 * @description A version of the factorial function that returns the result via a callback.
 * 
 * @param {number} n - The number for which to calculate the factorial.
 * @param {function} callback - The function to call with the result of the calculation.
 * 
 * @returns {void}
 * 
 * @example
 * factorialWithCallback(5, (error, result) => {
 *   if (error) {
 *     console.error(error);
 *   } else {
 *     console.log(result);
 *   }
 * });
 * // logs { input: 5, output: 120 }
 */
function factorialWithCallback(n, callback) {
  /**
   * @type {FactorialResult}
   */
  const result = {
    input: n,
    output: factorial(n),
  };
  try {
    callback(null, result);
  } catch (error) {
    callback(error);
  }
}

• @callback

/**
 * @typedef {Object} FactorialResult
 * 
 * @property {number} input - The input to the factorial function.
 * @property {number} output - The output of the factorial function.
 */

/**
 * @callback FactorialCallback
 * 
 * @param {Error} error - The error that occurred during the calculation, if any.
 * @param {FactorialResult} result - The result of the calculation.
 */

/**
 * @description A function that calculates the factorial of a number using recursion.
 * 
 * @param {number} n - The number for which to calculate the factorial.
 * 
 * @returns {number} The factorial of `n`.
 * 
 * @throws {TypeError} If the input is not a number.
 * 
 * @example
 * factorial(5);
 * // returns 120
 */
function factorial(n) {
  if (typeof n !== "number") {
    throw new TypeError("Input must be a number");
  }
  if (n === 0) {
    return 1;
  }
  return n * factorial(n - 1);
}

/**
 * @description A version of the factorial function that returns the result via a callback.
 * 
 * @param {number} n - The number for which to calculate the factorial.
 * @param {FactorialCallback} callback - The function to call with the result of the calculation.
 * 
 * @returns {void}
 * 
 * @example
 * factorialWithCallback(5, (error, result) => {
 *   if (error) {
 *     console.error(error);
 *   } else {
 *     console.log(result);
 *   }
 * });
 * // logs { input: 5, output: 120 }
 */
function factorialWithCallback(n, callback) {
  /**
   * @type {FactorialResult}
   */
  const result = {
    input: n,
    output: factorial(n),
  };
  try {
    callback(null, result);
  } catch (error) {
    callback(error);
  }
}

Jenis tersebut FactorialCallbackkemudian direferensikan dalam @paramtag untuk parameter callback dari factorialWithCallbackfungsi tersebut.

Contoh/Demo

Pratinjau cuplikan di atas dan dokumentasi yang dihasilkannya menggunakan JS Doc dapat diperiksa di sini .

Harap diperhatikan bahwa contoh ini adalah implementasi yang sangat disederhanakan untuk menunjukkan kepada pembaca potensi yang dapat dibuka setelah semua teknik ini dipahami dan diterapkan dalam proyek mereka.

Ringkasan

Di dunia yang penuh dengan basis kode yang kompleks dan rumit, komentar kode adalah teman yang kita semua butuhkan. Dengan manfaat mulai dari keterbacaan kode yang lebih baik hingga dokumentasi yang dibuat secara otomatis, alat seperti JS Doc sangat penting untuk perangkat pengembangan apa pun.

Apakah Anda seorang pengembang berpengalaman atau baru memulai, meluangkan waktu untuk mendokumentasikan kode Anda dengan cara standar tidak hanya akan menguntungkan produk dalam jangka pendek, tetapi juga memastikan umur panjang dan pemeliharaan basis kode untuk tahun-tahun mendatang.

Saya mendorong Anda untuk menggunakan sistem ini ke dalam proyek Anda. Percayalah, diri Anda di masa depan akan berterima kasih untuk itu!