Dalam pengembangan perangkat lunak, menulis kode yang bersih dan mudah dipahami sangat penting. Salah satu cara untuk mencapai ini adalah dengan menggunakan komentar (comments). Comments membantu pengembang lain (atau diri kita sendiri di masa depan) memahami maksud dan fungsi dari bagian kode tertentu. Sebuah komentar akan dilewatkan ketika proses kompilasi, sehingga tidak akan memengaruhi alur program yang kita tulis. Komentar bisa digunakan sebagai dokumentasi yang menjelaskan kode yang kita tulis. Pada artikel ini, kita akan membahas jenis-jenis comments yang tersedia di Dart, bagaimana penggunaannya, serta praktik terbaik dalam menulis comments.

Jenis-jenis Comments di Dart

Dart sama halnya seperti banyak bahasa pemrograman lainnya, yaitu mendukung beberapa jenis comments:

1. Single-line Comments

2. Multi-line Comments

3. Documentation Comments

Single-line Comments

Single-line comments dimulai dengan dua garis miring (//). Comments ini digunakan untuk menulis catatan singkat pada satu baris.

// Ini adalah single-line comment
int number = 21; // Menyimpan nilai 21 ke dalam variabel 'number'

Multi-line Comments

Multi-line comments dimulai dengan garis miring bintang (/*) dan diakhiri dengan bintang garis miring (*/). Comments ini berguna untuk menulis catatan yang lebih panjang atau menonaktifkan blok kode sementara waktu.

/* 
Ini adalah multi-line comment.
Dapat digunakan untuk menulis catatan yang lebih panjang.
*/
int anotherNumber = 43;

Documentation Comments

Documentation comments adalah jenis khusus dari comments yang digunakan untuk mendokumentasikan API. Comments ini dimulai dengan tiga garis miring (///) atau /** dan diakhiri dengan */. Tools seperti DartDoc dapat menggunakan documentation comments ini untuk menghasilkan dokumentasi otomatis. Di dalam documentation comments, kompiler Dart akan mengabaikan semua teks kecuali yang tertutup dalam kurung siku ([]). Di dalam kurung siku kita dapat memasukkan referensi dari nama kelas, variabel, atau fungsi. Berikut ini adalah contoh penggunaan komentar.

/// Menghitung jumlah dua angka.
/// 
/// Mengambil dua parameter [a] dan [b] yang merupakan bilangan bulat, 
/// dan mengembalikan jumlahnya.
int sum(int a, int b) {
  return a + b;
}

Praktik Terbaik dalam Menulis Comments

Menulis comments yang efektif adalah seni tersendiri. Berikut beberapa praktik terbaik yang bisa kita ikuti:

1. Jelaskan "Mengapa" bukan "Bagaimana"

   Comments seharusnya menjelaskan alasan mengapa suatu bagian kode ditulis dengan cara tertentu, bukan cara kerjanya. Kode yang baik seharusnya sudah cukup jelas dalam hal "bagaimana".

2. Jaga Agar Tetap Relevan dan Terupdate

   Pastikan comments selalu relevan dengan kode yang ada. Saat memperbarui kode, jangan lupa memperbarui comments terkait.

3. Gunakan Bahasa yang Jelas dan Sederhana

   Tulis comments dengan bahasa yang mudah dimengerti. Hindari jargon teknis yang tidak perlu.

4. Hindari Comments yang Redundant

   Comments yang hanya mengulangi apa yang sudah jelas dari kode adalah hal yang tidak perlu. Misalnya:

    int count = 10; // Mengatur count menjadi 10 (redundant)
   

5. Dokumentasikan API dengan Baik

   Untuk fungsi, kelas, dan metode publik, gunakan documentation comments. Ini membantu dalam menghasilkan dokumentasi yang berguna bagi pengembang lain yang menggunakan API Anda.

Oke, jadi begitulah beberapa jenis dan praktik menggunakan komentar (comments). Comments adalah alat yang sangat berguna dalam pemrograman jika digunakan dengan benar. Di Dart, kita memiliki beberapa jenis comments yang bisa digunakan sesuai kebutuhan: single-line, multi-line, dan documentation comments. Cukup sekian mungkin untuk artikel kali ini, kamu bisa subscribe dan share artikel ini jika bermanfaat.