Komentar dan Konvensi

Komentar dan konvensi penamaan membuat kode dapat dibaca kembali oleh penulisnya sendiri maupun oleh pengembang lain tanpa membongkar logikanya dari awal. Topik ini membahas penulisan komentar baris dengan kutip satu, komentar dokumen XML dengan tiga kutip satu yang dimanfaatkan oleh IntelliSense, konvensi penamaan pengenal yang diikuti dokumentasi resmi, dan Option Explicit yang menuntut setiap variabel dideklarasikan lebih dahulu.

Komentar baris dengan kutip satu#

Komentar ditulis dengan tanda kutip satu (') dan berlaku sampai akhir baris, baik pada baris tersendiri maupun di sebelah kanan pernyataan. Compiler mengabaikan seluruh isi komentar, sehingga kehadirannya tidak mengubah keluaran program sedikit pun. Komentar yang baik menyatakan maksud kode, dan bukan sekadar mengulang terjemahan barisnya.

Program berikut memuat komentar pada tiga posisi berbeda sekaligus menjadi berkas utama topik ini.

Module Program

    ''' <summary>
    ''' Menghitung luas persegi panjang dari panjang dan lebarnya.
    ''' </summary>
    ''' <param name="panjang">Panjang sisi dalam meter.</param>
    ''' <param name="lebar">Lebar sisi dalam meter.</param>
    ''' <returns>Luas dalam meter persegi.</returns>
    Function LuasPersegiPanjang(panjang As Double, lebar As Double) As Double
        ' mengalikan kedua sisi secara langsung
        Return panjang * lebar
    End Function

    Sub Main()
        ' menampilkan luas untuk ukuran 4 meter dan 2,5 meter
        Console.WriteLine(LuasPersegiPanjang(4, 2.5))
    End Sub

End Module

10

Komentar ' mengalikan kedua sisi secara langsung menegaskan maksud baris Return, sedangkan komentar pada Sub Main menjelaskan data yang digunakan pemanggilan. Komentar di dalam string tetap diperlakukan sebagai teks, sehingga tanda kutip satu di dalam "..." tidak memulai komentar. Kebiasaan lain yang umum adalah menonaktifkan satu baris kode dengan mengomentarinya saat mencoba pendekatan lain, teknik yang berguna ketika menyelidiki perilaku program tanpa menghapus baris aslinya.

Komentar dengan Rem#

Kata kunci Rem adalah bentuk komentar yang lebih tua dan berfungsi sama dengan kutip satu, yaitu menandai sisanya sebagai teks yang diabaikan compiler. Kata Rem sendiri berasal dari remark, sebutan untuk catatan pada kode. Rem wajib berada di awal pernyataan sehingga komentar berdampingan dengan pernyataan lain pada satu baris tidak menggunakannya, sedangkan kutip satu bebas diletakkan di mana saja.

' tidak-dijalankan
Rem Menghitung total belanja
Rem Total As Decimal = 0D ' baris ini tetap komentar, bukan kode
' kutip satu lebih ringkas dan lebih umum dipakai

Dokumentasi resmi menyebut Rem dipertahankan demi kesesuaian dengan versi-versi VB terdahulu. Penggunaan kutip satu menjadi pilihan utama karena lebih ringkas, sedangkan Rem cukup dikenali agar kode lama tetap terbaca.

Komentar dokumen XML#

Komentar dokumen XML ditulis dengan tiga kutip satu (''') dan diletakkan tepat di atas deklarasi tipe, prosedur, atau properti yang didokumentasikan. Tag yang paling sering digunakan adalah <summary> untuk keterangan umum, <param> untuk setiap parameter, dan <returns> untuk nilai kembalian. Visual Studio menampilkan isi komentar ini pada jendela IntelliSense saat fungsi tersebut diketik, sehingga keterangan itu terbaca tanpa membuka berkas definisinya.

Komentar dokumen pada LuasPersegiPanjang di atas adalah contohnya, dan pemanggilan fungsi tersebut di Sub Main akan menampilkan ringkasannya ketika diketik di editor. Compiler juga dapat mengekstrak seluruh komentar dokumen menjadi berkas XML untuk dibuat dokumentasinya.

Komentar dokumen menuntut isi XML yang benar, sehingga tag yang ditulis tanpa penutup yang seimbang memicu error saat dokumentasi diaktifkan. Tag yang salah posisi, misalnya <param> pada prosedur tanpa parameter, juga tertangkap pemeriksaan yang sama.

Konvensi penamaan pengenal#

Konvensi penamaan menetapkan bentuk huruf untuk setiap jenis pengenal sehingga pembacaan kode lebih cepat dan pencarian nama lebih mudah. Dokumentasi resmi VB.NET mengikuti dua gaya utama, yaitu PascalCase untuk jenis dan anggota yang lebih luas jangkauannya serta camelCase untuk variabel lokal dan parameter.

Nama pengenal disarankan menjelaskan isinya secara utuh dan bukan singkatan yang hanya dipahami penulisnya. totalDetik lebih jelas daripada td, sedangkan singkatan seperti txt atau awalan jenis seperti strNama bukan bagian dari konvensi VB.NET modern.

Option Explicit#

Option Explicit On menuntut setiap variabel dideklarasikan dengan Dim atau pernyataan serupa sebelum digunakan, dan pengaturan ini aktif secara default pada proyek baru. Kesalahan yang paling sering tertangkap oleh pengaturan ini adalah salah ketik nama variabel, karena nama yang tidak dideklarasikan langsung dilaporkan dan bukan diam-diam diperlakukan sebagai variabel baru. Penetapannya dapat dilakukan di berkas .vbproj proyek atau di baris pertama berkas sumber.

' tidak-dijalankan
jumlah = 10 ' error BC30451: 'jumlah' tidak dideklarasikan

Pada kode di atas, variabel yang dimaksud penulis mungkin bernama jumlahBarang, tetapi tanpa deklarasi compiler tidak memiliki cara untuk memastikannya. Pesan BC30451 menyebut nama yang tidak dideklarasikan tersebut, dan perbaikannya adalah mendeklarasikan variabel dengan Dim sebelum penugasan. Menonaktifkan pengaturan ini dengan Option Explicit Off memang dimungkinkan, tetapi kebiasaan itu menyembunyikan salah ketik dan bukan gaya yang dianjurkan.

Kesalahan umum#

Tiga kesalahan berikut paling sering muncul pada penggunaan komentar dan penamaan.

1. Menulis komentar yang berlawanan dengan kode. Komentar yang tidak diperbarui saat kode berubah lebih menyesatkan daripada tanpa komentar, sehingga penyuntingan kode selalu diikuti penyuntingan komentarnya.
2. Memberi komentar pada setiap baris yang sudah jelas. Baris x = x + 1 cukup dibaca sendiri, sedangkan komentar bermanfaat pada bagian yang menyatakan maksud, misalnya alasan pemeriksaan tambahan.
3. Menggunakan nama singkat yang ambigu pada pengenal. Nama seperti a atau x2 memaksa pembaca menelusuri deklarasinya, sedangkan nama lengkap seperti jumlahBaris mencegah hal itu.

Ringkasan#

• Komentar baris menggunakan kutip satu dan berlaku sampai akhir baris, sedangkan Rem adalah bentuk lama yang fungsinya sama.
• Komentar dokumen XML dengan ''' di atas deklarasi memasok isi IntelliSense dan berkas dokumentasi, dengan tag utama <summary>, <param>, dan <returns>.
• Konvensi penamaan menggunakan PascalCase untuk tipe dan anggota serta camelCase untuk variabel lokal dan parameter, dan konvensi ini tidak ditegakkan compiler.
• Option Explicit On aktif secara default dan menolak penggunaan variabel yang belum dideklarasikan dengan error BC30451.

Referensi#

• Comments in Code — Microsoft Learn — Aturan penulisan komentar inline dan blok komentar XML.
• Rem Statement — Microsoft Learn — Pernyataan komentar bentuk lama yang masih didukung.
• Documenting Your Code With XML — Microsoft Learn — Pembuatan dokumentasi dari komentar XML beserta tag-tag utamanya.
• Naming Conventions — Microsoft Learn — Gaya huruf dan aturan penamaan pengenal yang dianjurkan.
• Option Explicit Statement — Microsoft Learn — Pengaturan kewajiban mendeklarasikan variabel.