Mengomentari sesuatu pada dasarnya adalah cara seseorang untuk menilai atau memberikan pandangan yang berbeda terhadap sesuatu, apakah itu dari segi baik atau buruk dalam prosesnya, kita akan mempertimbangkan apakah kita akan memperbaiki berdasarkan hal tersebut atau mengabaikannya saja, menurut komentar tersebut. yang diberikan kepada kami.

Tapi, dalam posting ini, kita tidak akan berbicara tentang politik, tetapi lebih teknis tentang Pengembangan Web, dan perspektif saya adalah mengapa kita perlu melakukan ini selama kita menulis kode kita.

Pada pembahasan kita kali ini, kita akan melihat betapa pentingnya mengomentari suatu fungsi yang telah kita buat sendiri, tentunya di JavaScript. Bayangkan kita memiliki fungsi seperti ini:

function setLocation(x, y) {
  window.location.href = `${x}://${y}`;
}

window.location.href = `${x}://${y}`;

Apa Penjelasan argumen `x`dan `y`? apakah kita akan mengisi `object`atau `string`atau mungkin kita bisa mengisi beberapa masukan khusus? lain kita menggunakan TypeScript, mekanisme tipe data akan dilakukan oleh TypeScript sendiri saat runtime atau mungkin saat pengembangan , tapi bagaimana kalau kita menggunakan JavaScript?

Ya, dalam JavaScript (JS) argumen dalam `setLocation`fungsi akan ditampilkan oleh editor IntelliSense`any` artinya data apa pun akan diizinkan.

Seperti yang Anda lihat pada dasarnya, ada dua masalah di sini; Komputer dan Manusia , ketika komputer membaca kode akan terus berjalan tidak peduli nama argumen yang telah kita tetapkan, tapi bagaimana dengan Manusia ?

Fungsi yang kita buat akan sulit dipahami oleh developer (Manusia) berikutnya, karena tanpa mengetahui apa yang harus dikirim ke `setLocation`fungsi tersebut, beda halnya jika kita memberikan komentar

// args `x` with data type string, is a protocol
// args `y` with data type string, is a domain name
function setLocation(x, y) {
  window.location.href = `${x}://${y}`;
}

Kami akan mencoba mengomentari fungsi yang kami buat, sesuai dengan standar JSDoc , kami akan mengubah komentar di atas menjadi seperti ini

/**
 * A function that can be executed on address bar browser
 * @param {string} x a host url
 * @param {string} y a domain url
 */
function setLocation(x, y) {
  window.location.href = `${x}://${y}`;
}

Memang, IntelliSense itu hanya membantu pengguna untuk menentukan apa yang harus dikirim dalam fungsi itu ketika kita ingin menggunakannya, tetapi itu tidak sepenuhnya ketat .

Ini sangat membantu terutama jika kita memiliki fungsi dimana kita harus mengirimkan objek data sebagai parameter dari fungsi tersebut, misalnya kita memiliki fungsi seperti ini

/**
 * @param {object} fullName
 * @param {string} fullName.firstName your first name
 * @param {string} fullName.lastName your last name
 */
function overwriteData(fullName) {
  return {
    firstName: "Adib",
    lastName: "Firman",
    ...fullName
  };
}

Sama seperti biasa IntelliSense akan memberi kami petunjuk, dan Anda tahu bahwa pendekatan ini lebih menarik

Pada gambar di atas kita akan memasukkan data sesuai dengan instruksi dari IntelliSense tentunya kita akan mendapatkan petunjuk dari editor kita, menarik bukan?

Pertanyaan selanjutnya adalah, haruskah kita mengomentari semua fungsi yang telah kita buat? Tentu tidak, contoh fungsinya seperti ini

const sum = (firstNum, secondNum) => firstNum + secondNum;

Kesimpulan

Berilah beberapa komentar pada fungsi kita, tergantung pada bagaimana penggunaannya, apakah parameter yang diberikan sangat kompleks ? atau apakah itu dapat dibaca dari fungsi penamaan dan argumen yang dibuat?

Namun jika merasa fungsi tersebut perlu diberi komentar, itu lebih baik, karena untuk memudahkan pemeliharaan oleh developer selanjutnya (Human).

Terima kasih.