Menarik, bahwa keterbacaan sebagaimana diterapkan pada bahasa alami diukur dengan kecepatan membaca dan pemahaman. Saya kira aturan sederhana memang bisa diadopsi, jika komentar kode tertentu tidak meningkatkan properti ini, itu bisa dihindari .
Kenapa berkomentar?
Meskipun, komentar kode adalah bentuk dokumentasi yang disematkan, ada beberapa cara dalam bahasa pemrograman kelas atas untuk menghindari pemrograman yang "terlalu banyak didokumentasi" (dari kode yang bermakna) dengan menggunakan elemen-elemen dari bahasa itu sendiri. Ini juga merupakan ide yang buruk untuk mengubah kode menjadi daftar dari buku teks pemrograman, di mana pernyataan individu secara harfiah dijelaskan dalam cara yang hampir tautologis (ingat contoh kenaikan "/ * oleh 1 * /" dalam jawaban yang sudah disediakan), membuat komentar seperti itu relevan hanya untuk programmer yang tidak berpengalaman dengan bahasa.
Meskipun demikian, niat untuk mencoba mengomentari kode "yang tidak terdokumentasi" (tetapi tidak berarti) itulah yang benar-benar "sumber segala kejahatan". Keberadaan kode "yang tidak didokumentasikan" adalah pertanda buruk - baik itu kekacauan yang tidak terstruktur, atau peretasan aneh dari tujuan mistis yang hilang. Jelas, nilai kode semacam itu setidaknya dipertanyakan. Sayangnya selalu ada contoh, ketika memang lebih baik untuk memasukkan komentar ke dalam bagian (secara visual dikelompokkan) baris kode daripada membungkusnya menjadi subrutin baru (pikiran "konsistensi bodoh" yang "adalah hobgoblin dari pikiran kecil") .
Pembacaan kode! = Komentar kode
Kode yang dapat dibaca tidak membutuhkan penjelasan oleh komentar. Di setiap tempat tertentu dalam kode selalu ada konteks tugas yang harus dicapai oleh kode khusus ini. Jika tujuan tidak ada dan / atau kode melakukan sesuatu yang misterius = hindarilah dengan cara apa pun. Jangan biarkan peretasan aneh mengisi kode Anda - ini adalah hasil langsung dari penggabungan teknologi kereta dengan kurangnya waktu / minat untuk memahami dasar-dasarnya. Hindari kode mistik dalam proyek Anda!
Di sisi lain, program yang dapat dibaca = kode + dokumentasi dapat berisi beberapa bagian komentar yang sah, misalnya untuk memfasilitasi pembuatan dokumentasi "komentar ke API".
Ikuti standar gaya kode
Cukup lucu pertanyaannya bukan tentang mengapa berkomentar kode, ini tentang kerja tim - bagaimana menghasilkan kode dengan gaya yang sangat disinkronkan (yang orang lain dapat membaca / mengerti). Apakah Anda mengikuti standar gaya kode di perusahaan Anda? Tujuan utamanya adalah untuk menghindari penulisan kode yang memerlukan refactoring, terlalu "pribadi" dan "subyektif" ambigu. Jadi saya kira, jika seseorang melihat perlunya menggunakan gaya kode, ada alat yang serius bagaimana menerapkannya dengan benar - dimulai dengan mendidik orang dan berakhir dengan otomatisasi untuk kontrol kualitas kode (banyak serat, dll) dan (revisi) kontrol terintegrasi) sistem peninjauan kode.
Menjadi penginjil pembacaan kode
Jika Anda setuju bahwa kode dibaca lebih sering daripada yang tertulis. Jika ekspresi ide dan pemikiran yang jelas jelas penting bagi Anda, tidak peduli bahasa apa yang digunakan untuk berkomunikasi (matematika, kode mesin atau bahasa Inggris kuno) .. Jika misi Anda adalah untuk menghilangkan cara berpikir alternatif yang membosankan dan jelek .. (maaf , yang terakhir adalah dari "manifes" lain) .. mengajukan pertanyaan, memulai diskusi, mulai menyebarkan pemikiran buku tentang pembersihan kode (mungkin bukan hanya sesuatu yang mirip dengan pola desain Beck, tetapi lebih seperti yang telah disebutkan oleh RC Martin ) yang membahas ambiguitas dalam pemrograman. Lebih jauh pergi bagian poin-poin ide-ide kunci (dikutip dari buku O'Reilly tentang keterbacaan)
- Sederhanakan penamaan, komentar, dan pemformatan dengan tips yang berlaku untuk setiap baris kode
- Perbaiki loop, logika, dan variabel program Anda untuk mengurangi kompleksitas dan kebingungan
- Menyerang masalah di tingkat fungsi, seperti mengatur ulang blok kode untuk melakukan satu tugas sekaligus
- Tulis kode uji efektif yang menyeluruh dan ringkas — serta dapat dibaca
Memotong "mengomentari", seseorang masih memiliki banyak (saya kira menulis kode yang tidak perlu komentar adalah salah satu latihan yang hebat!). Memberi nama pengidentifikasi yang secara semantik bermakna adalah awal yang baik. Selanjutnya, susun kode Anda dengan mengelompokkan operasi yang terhubung secara logis ke dalam fungsi dan kelas. Dan seterusnya. Programmer yang lebih baik adalah penulis yang lebih baik (tentu saja, dengan asumsi keterampilan teknis lain yang diberikan).