Dulu saya berpikir bahwa saya tidak perlu komentar jika saya menulis kode yang mendokumentasikan diri sendiri. Namun, saya menyadari bahwa saya sedang menulis komentar dan merasa sangat membantu. Untuk melihat berapa banyak komentar yang saya tulis dan apa komentarnya, saya menulis skrip untuk menganalisis komit git saya selama enam tahun terakhir. Secara total, tujuh persen dari baris saya yang disetujui berisi komentar. Posting ini memiliki detail tentang apa yang dianggap sebagai komentar baik dan buruk, serta statistik tambahan dari skrip saya.
Javadoc adalah yang paling tidak berguna
Salah satu alasan saya skeptis tentang komentar adalah dominasi komentar gaya Javadoc. Gaya berkomentar ini juga ada dalam bahasa lain. Berikut adalah contoh Python yang baru saja saya buat, tetapi yang mewakili gaya ini:
Masalah dengan sebagian besar komentar ini adalah bahwa mereka menyampaikan informasi yang sangat sedikit. Seringkali hanya mengulangi nama metode dan nama parameter dalam beberapa kata. Komentar ini dapat berguna untuk API yang terpapar secara eksternal, tetapi dalam aplikasi di mana Anda memiliki akses ke semua kode sumber, sebagian besar tidak berguna. Jika Anda bertanya-tanya apa yang dilakukan suatu metode atau apa rentang input yang valid untuk suatu parameter, Anda sebaiknya membaca kode untuk melihat apa fungsinya. Jenis komentar ini memakan banyak ruang tetapi tidak terlalu berharga.
Kode yang mendokumentasikan diri sendiri
Daripada menulis komentar Javadoc, yang terbaik adalah memanfaatkan nama metode dan nama variabel. Setiap nama yang Anda gunakan dapat membantu menjelaskan tentang apa itu dan bagaimana melakukannya. Salah satu alasan bagus untuk menulis banyak metode kecil daripada satu metode besar adalah karena Anda memiliki lebih banyak tempat untuk menggunakan nama deskriptif, yang saya jelaskan di sini .
Kapan harus berkomentar
Menulis kode yang mendokumentasikan diri sendiri akan membantu Anda dalam jangka panjang. Namun, ada kalanya sangat membantu untuk memiliki lebih banyak informasi. Misalnya, komentar tentang penggunaan zona panggilan pada kode di bawah ini:
Contoh lain:
Anda sering mendengar saran "tulis komentar MENGAPA, bukan APA". Meskipun ini mungkin mencakup sebagian besar komentar saya, ini bukan cara saya berpikir tentang kapan harus berkomentar. Sebagai gantinya, saya biasanya menulis komentar ketika ada sesuatu yang sangat rumit, baik dalam domain atau bagaimana implementasinya dilakukan.
Saran standar dari kerumunan "tidak perlu komentar" (yang pernah saya ikuti) adalah menulis ulang kode sehingga Anda tidak perlu mengomentarinya. Namun, ini tidak selalu mungkin. Terkadang domain terlalu rumit. Terkadang upaya untuk menulis ulang kode akan terlalu besar dibandingkan dengan menambahkan komentar.
Keluhan lain tentang komentar adalah bahwa komentar akan tidak sinkron dengan kode, sehingga menghambat pemahaman Anda tentang kode, daripada membantunya. Meskipun itu kadang-kadang terjadi, itu bukan masalah besar bagi saya. Di hampir semua kasus yang saya analisis, komentarnya masih valid. Mereka juga sangat membantu. Setiap kali saya menemukan salah satu komentar ini, saya senang bahwa saya menulisnya. Tidak butuh waktu lama untuk melupakan beberapa detail dan nuansa dari masalah yang Anda pecahkan, dan memberikan komentar dengan beberapa konteks dan penjelasan tambahan sangat bagus.
Log sebagai komentar
Terkadang Anda mendapatkan komentar gratis jika Anda mendaftarkan pesan penjelasan. Pada contoh di bawah, pernyataan log menjelaskan apa yang terjadi, jadi tidak perlu komentar.
Analisis komentar
Ketika saya pertama kali berpikir untuk memeriksa berapa banyak komentar di semua komit saya, saya pikir satu baris akan cukup untuk menemukan komentar di semua komit Python saya (saya hanya berkomentar dengan #):
git log --author = Henrik -p | grep '^ + [^ +]' | grep '#' | wc -l
Namun, saya segera menyadari bahwa saya membutuhkan lebih banyak detail. Saya ingin membedakan antara komentar akhir baris dan komentar seluruh baris. Saya juga ingin tahu berapa banyak "blok komentar" (baris komentar berturut-turut) yang saya miliki. Saya juga memutuskan untuk mengecualikan file uji dari analisis. Selain itu, saya ingin memastikan untuk mengecualikan kode yang dikomentari yang berakhir di sana (sayangnya, ada beberapa kasus seperti itu). Saya akhirnya menulis skrip python untuk melakukan analisis. Input ke skrip adalah output dari git log --author = Henrik -p.
Dari output, saya melihat 1299 dari 17817 baris yang saya tambahkan berisi komentar. Ada 161 komentar akhir baris dan 464 komentar satu baris. Blok komentar terpanjang adalah 11 baris, dan ada 96 kasus blok komentar yang memiliki 3 baris atau lebih berturut-turut.
kesimpulan
Saya dulu berpikir bahwa menulis fungsi yang diberi nama baik berarti tidak perlu komentar. Namun, melihat apa yang sebenarnya saya lakukan, saya perhatikan bahwa saya cenderung menambahkan komentar ke bagian kode yang kompleks atau tidak intuitif. Setiap kali saya mengunjungi kembali bagian-bagian program ini, saya senang saya berusaha untuk menambahkan komentar - mereka sangat membantu!