Beberapa minggu terakhir ini saya mengerjakan game dalam tim yang terdiri dari dua programmer, dan beberapa hari yang lalu saya diminta untuk menggantikan tugas seorang programmer di tim yang lebih besar lagi. Hal pertama yang terpikir oleh saya jika membicarakan tim dengan banyak programmer adalah ‘kodenya harus rapi dan well commented‘. Selain agar mudah dibaca jika sewaktu-waktu programmer lain dalam tim butuh untuk menambahkan kode di bagian saya, game yang besar berpeluang untuk berjalan dalam waktu yang cukup lama, sehingga pasti akan banyak penambahan fitur atau setidaknya maintenance.
Hal pertama yang saya lakukan adalah memanfaatkan fitur yang ada pada IDE yang saya gunakaan saat itu (FlashDevelop), yaitu fitur code snippetnya. Komentar saya dibuat sedemikian rupa sehingga tidak memakan banyak baris, namun tetap muncul di pop-up pada IDE (misalnya pada penjelasan fungsi atau parameternya). Sempat juga mencoba documentation generator seperti Ortelius, yang bisa terintegrasi dengan FlashDevelop untuk membuat dokumentasi, namun dibatalkan karena ada ketidakcocokan dengan format komentar yang saya gunakan.
Ada beberapa tips dalam membuat komentar pada source code, yang saya rangkum sebagai berikut:
- Tulis komentar dengan rapi dan konsisten. Gunakan indentasi yang benar dan seragam, beri komentar untuk setiap properti dan fungsi yang dibuat.
- Tulis komentar dengan jelas dan mudah dimengerti. Namun jangan menggangap remeh calon pembaca komentar Anda dengan menjelaskan “if(a==5)” dengan “//jika a sama dengan 5″. Asumsikan calon pembaca adalah sesama programmer atau diri Anda sendiri di masa depan.
- Gunakan tag khusus jika perlu. Tag yang umum digunakan misalnya “//TODO:” atau “//FIXME:”
- Tulis komentar selagi Anda membuat kode atau mengupdate kode. Karena percayalah, membuat komentar untuk kode yang sudah selesai sama merepotkannya dengan menulis ulang kode-kode itu.
- Tambahan dari saya, “Tell what do you do, not how do you do“. Artinya beritahu apa pekerjaan Anda, bukan kabar Anda tulis tujuan dari sebuah bagian kode, bukan bagaimana kode tersebut bekerja. Misalnya “hitung c yang merupakan selisih b dan a”, tapi lebih baik “c adalah vektor AB”.
Sekian beberapa tips yang saya tahu, semoga bisa berguna untuk yang membutuhkan.
Cheers… :D









Komentar pada kode adalah tanda kelemahan
Tags: comment, source code
Berkebalikan dengan post saya minggu lalu yang menyatakan bahwa komentar dalam source code itu penting, pada post ini saya akan mencoba menjelaskan kenapa kita tidak perlu memberi komentar pada kode kita.
Tepat di hari saya menulis post tentang tips mengomentari kode, saya menemukan post tentang menghilangkan komentar sebagai jalan menuju kejelasan. Kinda random but thanks Google Reader! :D
Quote dari post tersebut:
Contoh kasus penggunaan komentar dan tidak:
bandingkan dengan kode berikut:
Tanpa menggunakan komentar, kode pada bagian kedua tetap mudah dimengerti. The code is self-documenting. Nama variabel dan nama fungsi sudah cukup merepresentasikan isi atau tujuan dari potongan kode tersebut. “If you have something important to say, put it in the code.“
Berikut adalah beberapa kelemahan komentar:
Hampir setengah minggu saya gunakan untuk mencoba teknik ini, dan cukup membuat kode saya lebih rapi dan lebih mudah dibaca. Rencananya di akhir bulan ini saya akan coba evaluasi teknik mana yang lebih cocok untuk kondisi saya sekarang.
Bagaimana menurut Anda? Pentingkah memberi komentar pada kode Anda? :D