Apakah Lebih Banyak Komentar yang Lebih Baik di Lingkungan Pergantian Tinggi?

Saya sedang berbicara dengan seorang rekan hari ini. Kami mengerjakan kode untuk dua proyek berbeda. Dalam kasus saya, saya satu-satunya orang yang mengerjakan kode saya; dalam kasusnya, banyak orang bekerja pada basis kode yang sama, termasuk siswa koperasi yang datang dan pergi secara teratur (antara setiap 8-12 bulan). Dia mengatakan bahwa dia liberal dengan komentarnya, menempatkan semuanya di tempat itu. Alasannya adalah itu membantunya mengingat di mana segala sesuatu berada dan apa yang dilakukan karena banyak kode tidak ditulis olehnya dan dapat diubah oleh orang lain selain dirinya. Sementara itu, saya mencoba meminimalkan komentar dalam kode saya, menempatkannya hanya di tempat dengan solusi atau bug yang tidak terlihat. Namun, saya memiliki pemahaman yang lebih baik tentang kode saya secara keseluruhan, dan memiliki lebih banyak kontrol langsung terhadapnya.

Pendapat saya bahwa komentar harus minimal dan kode harus menceritakan sebagian besar cerita, tetapi alasannya juga masuk akal. Apakah ada kekurangan dalam alasannya? Ini mungkin mengacaukan kode tetapi pada akhirnya bisa sangat membantu jika ada banyak orang yang mengerjakannya dalam jangka pendek hingga menengah.

Komentar tidak mengacaukan kode.

Dan ketika mereka melakukannya, well, setiap IDE yang layak dapat menyembunyikan / melipat komentar. Idealnya cerita harus diceritakan oleh kode Anda, dokumen persyaratan Anda, riwayat komit Anda dan tes unit Anda, dan bukan oleh komentar. Namun, komentar yang berlebihan hanya bisa menyakitkan ketika komentar terkonsentrasi pada bagaimana dan bukan mengapa, namun itu adalah diskusi yang berbeda .

Saya pikir Anda dan kolega Anda "benar", bedanya, tentu saja, bahwa Anda bekerja sendiri dan dia dalam sebuah tim, yang sering kali menyertakan pengembang yang tidak berpengalaman. Anda tidak memiliki banyak filosofi yang berbeda pada komentar, tetapi persyaratan yang sangat berbeda dalam mengkomunikasikan kode Anda. Argumen "itu membantu saya mengingat" juga bisa berasal dari kenyataan bahwa dia berurusan dengan kode lebih banyak daripada Anda, dan lebih penting lagi kode yang diproduksi oleh orang yang berbeda, masing-masing dengan preferensi dan kebiasaan pribadi mereka sendiri.

Pada akhirnya, komentar kode, meskipun kelemahannya jelas, adalah cara paling sederhana dan tercepat untuk mengkomunikasikan kode Anda. Bergantung pada komposisi dan organisasi tim, itu mungkin satu-satunya cara yang berlaku untuk penyebut umum terendah. Saya biasanya mendapati diri saya mengikuti filosofi komentar Anda ketika bekerja sendiri dan menyesuaikan diri dengan rekan kerja Anda ketika bekerja dalam sebuah tim, terutama jika itu adalah keterampilan tim yang tidak seimbang.

Komentar progresif dalam lingkungan semacam itu menutupi untuk masalah yang harus dipecahkan dengan cara lain.

Kode yang berkualitas dan mudah dibaca tidak perlu membutuhkan komentar tambahan untuk menjelaskan apa yang dilakukannya. Satu-satunya waktu untuk berkomentar adalah ketika Anda ingin menjelaskan mengapa sesuatu dilakukan dengan cara tertentu. Dan bahkan kemudian, komentar-komentar itu bisa dibilang dalam kontrol komit sumber pesan.

Jadi, masalah yang dia selesaikan adalah dia harus bekerja dengan siswa yang tidak tahu bagaimana menulis kode mereka dengan cara yang dapat dibaca. Menurut pendapat saya, mengacaukan kode dengan komentar adalah solusi yang lemah untuk masalah itu.

Ulasan kode yang ketat akan jauh lebih efektif, baik dalam menjaga kode tetap rapi dan dalam meningkatkan siswa untuk masa depan, apakah itu di perusahaan yang sama atau di tempat lain.

Masalah dengan komentar adalah bahwa mereka cenderung tidak selaras dengan kode dengan sangat cepat. Ini berarti sering ada komentar yang keliru atau jelas-jelas salah dalam kode, sehingga mereka lebih merusak keterbacaan daripada membantu.

Tujuannya adalah membuat basis kode mudah dipahami dan dimodifikasi. Anda dapat melakukan ini melalui penggunaan komentar yang bebas (meskipun Anda mungkin mengalami masalah dengan komentar data), atau Anda dapat menulis kode dokumentasi sendiri (sebanyak mungkin), dan hanya menggunakan komentar untuk menjelaskan hal yang tidak sepele "mengapa "pertanyaan. Entah pendekatan yang mungkin berhasil, tetapi tetap di saya bahwa untuk mengubah kode Anda harus memahami kode itu sendiri, dan bukan hanya komentar. Jadi, sementara komentar mungkin membantu Anda memahami kode, pada akhirnya Anda mungkin masih harus memahami kode itu sendiri. Dengan itu, saya lebih suka pendekatan kode mendokumentasikan diri. Tampaknya menjadi cara yang lebih langsung untuk membuat basis kode yang bersih.

"Apakah Lebih Banyak Komentar yang Lebih Baik di Lingkungan Pergantian Tinggi?"

Saya pikir mereka mungkin lebih buruk:

• Penulis yang berbeda akan menggunakan gaya dan tingkat rincian yang berbeda dan akan kurang memperbarui komentar oleh orang lain.

• Pendapat "Apa yang perlu dikomentari" berubah dari orang ke orang.

• Mereka melanjutkan praktik penulisan kode yang sulit dibaca dengan komentar untuk menjelaskannya sebagai kebalikan dari kode yang mudah dibaca dengan nama deskriptif.

• Mempertahankan format dan konsistensi mereka menjadi pekerjaan tersendiri.

• Pengguna baru harus mempelajari standar 'format' sebelum dapat membuat perubahan cepat.

Butir 1: Kejelasan penting dalam lingkungan turnover tinggi

Butir 2: Verbositas bukan Kejelasan

Menambahkan komentar ke kode Anda mungkin atau mungkin tidak meningkatkan kejelasan; itu tergantung pada komentar yang Anda tambahkan. Dan setelah kejelasan optimal tercapai, komentar tambahan akan membuat situasi lebih buruk, tidak lebih baik.

Sementara komentar adalah komponen kejelasan, kualitas kode adalah komponen yang jauh lebih penting. Kepintaran adalah kebalikan dari kejelasan . Jika fungsi kode tidak segera terlihat melalui pembacaan biasa, maka kode tidak terlalu jelas, dan komentar (tidak peduli seberapa tinggi kualitas komentar itu) adalah pengganti yang buruk dan tidak efektif untuk kode yang jelas.

Misalnya, menjejalkan bendera di bidang yang tidak terkait erat mungkin diijinkan secara sempurna dalam keadaan tertentu, dan mungkin masuk akal dari perspektif kinerja dalam keadaan tertentu, tetapi itu hampir selalu merupakan ide yang buruk sehubungan dengan kejelasan. , bahkan jika Anda berkomentar sih.

Jika Anda merasa harus menjelaskan dalam prosa apa yang dilakukan kode Anda, maka pertimbangkan salah satu dari yang berikut: Perhatikan bahwa beberapa di antaranya dapat memengaruhi kinerja, tetapi kinerja mungkin tidak sepenting kejelasan dalam kasus-kasus tertentu.

• Nama variabel dan nama fungsi yang lebih baik
• Tata letak dan penspasian kode yang lebih baik
• Hapus "trik" yang menurut Anda adalah ide bagus
• Kode grup sesuai dengan fungsi konseptual (mis. Ekstrak kode untuk tujuan tertentu ke dalam fungsi yang diberi nama dengan tepat, bahkan jika Anda hanya menyebutnya sekali)
• Gunakan algoritma yang lebih lurus ke depan (kondisi memungkinkan)
• Gunakan perpustakaan terkenal untuk fungsionalitas umum

Sebuah jawaban yang terlalu disederhanakan: "Semakin besar kemungkinan kode Anda dibaca ulang, semakin tinggi beban untuk menjelaskan apa yang Anda lakukan." Ini bisa dengan membuat kode lebih mudah dibaca, dengan berkomentar, dengan membuat dokumentasi formal, dengan mengikuti standar gaya ... Harap dicatat bahwa mungkin Anda yang sedang membaca ulang nanti, meskipun tentu juga berlaku untuk orang lain dalam lingkungan turnover tinggi.

Ada utas lainnya yang mencakup apakah komentar merupakan dokumentasi atau bukan.

Komentar lebih bermanfaat dalam beberapa skenario daripada yang lain. Ini sangat mendasar sehingga saya khawatir bagaimana menjelaskannya di tengah begitu banyak jawaban yang saya anggap sebagai "anti-komentar".

Jika kode Anda mungkin tidak terbaca selama bertahun-tahun, komentar lebih penting daripada jika Anda sering melakukan refactoring kode, kepemilikan kode yang kuat, dan ulasan kode berlebihan. Jika aplikasi Anda rumit dan menggunakan teknik yang tidak segera jelas bagi pengamat yang mahir dalam bahasa itu, komentar lebih penting daripada jika sistemnya adalah "Hello World" yang dimuliakan. Jika basis kode tidak seketat standar, komentar lebih penting daripada jika Anda bekerja dengan enam lapis QA. Jika Anda bekerja dalam tim dengan delapan orang yang hanya mempelajari bahasa, komentar lebih penting daripada jika tim Anda memiliki delapan Pulitzer pemrograman. Jika Anda mendapatkan aplikasi luas jatuh di pangkuan Anda,komentar lebih penting daripada jika Anda dapat membuatnya bersih dari awal.

Apakah akan lebih baik di sebagian besar skenario untuk memperbaiki penyebab yang mendasarinya daripada meningkatkan penggunaan komentar? Benar. Tetapi kadang-kadang Anda terjebak dengan basis kode yang memiliki lebih banyak sidik jari daripada smartphone kota, dan cara terbaik untuk memperbaikinya adalah dengan membuat perubahan Anda semudah mungkin dibaca dan mengomentari hal itu.

Untuk masalah spesifik Anda: komentar tidak boleh berserakan sebanyak mengacaukan kode. Paragraf yang ditulis dengan baik di bagian atas subrutin, menjelaskan mengapa suatu fungsi ada dan mungkin mengapa menggunakan pendekatan itu, sering kali merupakan taruhan terbaik untuk membantu programmer berikutnya mendapatkan posisi mereka.