Apakah komentar yang sudah ketinggalan zaman merupakan mitos urban?

Saya terus-menerus melihat orang-orang membuat klaim bahwa "komentar cenderung menjadi ketinggalan zaman." Masalahnya, saya pikir saya telah melihat mungkin dua atau tiga komentar usang sepanjang karir saya. Informasi yang sudah ketinggalan zaman dalam dokumen terpisah terjadi setiap saat, tetapi dalam pengalaman saya komentar yang ketinggalan zaman dalam kode itu sendiri sangat jarang.

Apakah saya baru saja beruntung dengan siapa saya bekerja? Apakah industri tertentu lebih rentan terhadap masalah ini daripada yang lain? Apakah Anda memiliki contoh spesifik dari komentar lama yang baru saja Anda lihat? Atau komentar usang lebih dari masalah teoritis daripada yang sebenarnya?

Selalu

Aku benar-benar tidak percaya aku satu-satunya yang berenang di komentar usang dan menyesatkan. Jika hal ini membantu pemahaman:

Mungkin yang paling penting tergantung pada usia kode. Faktor selanjutnya adalah pergantian staf.

Saya melakukan bagian R&D yang sama dan pekerjaan pemeliharaan. R&D adalah kode baru, umumnya hal-hal yang sedikit keluar jalur. Banyak kolega saya percaya untuk memberikan banyak komentar ketika mencoba sesuatu yang belum ada perpustakaan di sana. Karena rasio komentar dengan kode lebih tinggi dari biasanya, ada lebih banyak peluang untuk hal-hal yang tidak sinkron.

Kode pemeliharaan ... Saya adalah pengelola aktif pada sistem yang berumur lebih dari 10 tahun dan lainnya yang lebih dari 5. Kode dan komentar berumur 10 tahun itu mengerikan, seperti yang Anda harapkan. Lebih dari 10 tahun Anda mendapatkan banyak tangan dalam basis kode dan tidak ada yang tahu bagaimana semuanya bekerja lagi. Kode dan komentar berusia 5 tahun cukup bagus karena omset tim sudah sangat rendah.

Saya mengerjakan hampir semua layanan, bahkan produk kami sangat disesuaikan untuk pelanggan tertentu.

Contoh spesifik:

• Komentar yang menjelaskan peningkatan kinerja untuk metodologi tertentu, seperti menghindari salinan dalam memori. Masalah besar ketika mesin kelas atas di Pentium 2 dengan MB RAM, tetapi sekarang bukan masalah.

• TODO

• Blok-blok kode yang disalin termasuk komentar. Komentar mungkin masuk akal di lokasi aslinya, tetapi hampir tidak masuk akal di sini

• Blok komentar di atas kode yang dikomentari (Siapa yang tahu berapa tahun sudah ada di sana).

Dalam semua ini Anda melihat tren tidak mempertahankan komentar dan kode pada tingkat yang sama dengan perangkat lunak. IDE dan kebiasaan dasar pengembang tidak membantu dengan ini, mata saya telah dilatih untuk melewatinya. Saya pikir komentar yang ketinggalan jaman relatif murah untuk dihindari dalam bidang hijau dan proyek aktif. Jika Anda dapat menjaga rasio kode / komentar tetap tinggi, bukan masalah besar untuk tetap memperbaruinya. Agak sulit untuk membenarkan memburu hal-hal ini ketika Anda dianggarkan x jam untuk perbaikan bug pada sistem produksi.

"Komentar cenderung menjadi usang."

Saya telah melihat ini terjadi cukup sering untuk mengetahui ini bisa menjadi masalah.

Masalahnya, saya pikir saya telah melihat mungkin dua atau tiga komentar usang sepanjang karir saya.

Saya percaya itu harus sangat mungkin untuk bekerja di lingkungan di mana semua orang cukup memperhatikan komentar dan mempertahankannya. Hanya sedikit usaha ekstra untuk melihat komentar di dekat kode yang sedang Anda edit dan memperbaruinya bila perlu. Jika komentarnya begitu jauh sehingga Anda tidak segera melihatnya, itu adalah komentar yang buruk, dan seharusnya tidak ditambahkan di tempat pertama (atau setidaknya tidak ada di sana).

Selain itu biasanya bersama dengan pernyataan bahwa komentar cenderung menjadi ketinggalan zaman, mengikuti pernyataan bahwa ini mengurangi keterbacaan dan membingungkan orang. Ini adalah sesuatu yang belum saya alami. Setiap kali saya menjumpai komentar yang kedaluwarsa, saya melihat dengan jelas apa yang berubah dan hanya memperbarui komentar yang sesuai untuk mewakili kode yang lebih baru, meskipun dengan upaya ekstra.

Sebuah studi terbaru oleh Roehm et al. 2012 mengamati hal-hal berikut:

21 peserta [dari 28] melaporkan bahwa mereka mendapatkan informasi utama dari kode sumber dan komentar inline sedangkan hanya empat yang menyatakan bahwa dokumentasi adalah sumber utama informasi mereka.

Ini sesuai dengan kecurigaan Anda bahwa komentar dalam kode itu sendiri umumnya masih dianggap sangat berguna. Ini menunjukkan bahwa garis yang jelas harus ditarik antara dokumentasi yang ketinggalan jaman dan komentar yang ketinggalan zaman .

_{Roehm, T., Tiarks, R., Koschke, R., & Maalej, W. (2012, Juni). Bagaimana pengembang profesional memahami perangkat lunak? Dalam Prosiding Konferensi Internasional 2012 tentang Rekayasa Perangkat Lunak (hlm. 255-265). IEEE Press.}

Komentar yang ketinggalan jaman adalah bau pekerjaan. Ini seperti memiliki unit test yang ketinggalan jaman atau diabaikan - ini menunjukkan bahwa proses bagus yang dulunya aktif di toko berubah menjadi pengkodean koboi. "Budaya rekayasa" yang tepat dalam meluangkan waktu untuk melakukan berbagai hal dengan benar telah hancur. Proyek / perusahaan kemungkinan masuk ke hutang teknis.

Singkatnya, ya, Anda beruntung. Jika Anda memiliki serangkaian toko yang dikelola dengan cukup baik sejauh ini dalam karir Anda, sangat mungkin untuk tidak melihat sebanyak ini. Tetapi di toko-toko yang lebih tipikal dan kurang dikelola dengan baik, ini berjalan paralel dengan kekacauan lainnya.

Komentar seperti tes, mereka sangat baik ketika mereka up to date, tetapi dapat membuatnya lebih sulit untuk memahami kode jika tidak ada.

Jika Anda tidak pernah melihat komentar yang ketinggalan zaman, Anda sangat beruntung.

Kebanyakan basis kode yang telah saya kerjakan penuh dengan komentar yang sudah ketinggalan zaman, dan biasanya saya mengabaikan komentar sepenuhnya karena biasanya merupakan sumber kebingungan alih-alih bantuan.

Komentar yang kedaluwarsa sering muncul di JavaDoc:

• Daftar argumen yang sudah tidak ada
• Tidak menjelaskan semua argumen (yang hilang kemungkinan ditambahkan kemudian)
• Hal serupa untuk pengecualian, dll.

Selain itu, terkadang komentar menyatakan hal-hal seperti "lakukan ini di sini untuk kinerja" ketika sebagian besar pertimbangan kinerja cenderung menjadi basi bahkan lebih cepat daripada kode itu sendiri.

Saya berurusan dengan komentar usang dari waktu ke waktu. Jelas itu bukan mitos urban. Orang-orang menyebutkannya dalam daftar praktik terburuk bukan karena sangat sering menyerang Anda, tetapi karena ketika melakukannya, biasanya Anda harus menghabiskan banyak waktu dan usaha.

Dalam basis kode kami, sebagian besar komentar yang ketinggalan zaman disebabkan oleh penggunaan pola (anti) untuk menggambarkan perilaku metode di dekat panggilannya dan bukan di dekat deklarasi metode. Itu terjadi ketika seseorang mengekstraksi potongan panjang kode ke dalam metode yang hanya dipanggil sekali pada saat itu dan kemudian mengomentari pemanggilan metode. Jadi Anda berakhir dengan sesuatu seperti ini:

featureList = GetFeatures();

// Sorting features and deleting empty ones from the list...
ProcessFeatures(featureList);

Dan metode ini dinyatakan di suatu tempat di bawah ini tanpa komentar. Orang-orang mengotak-atik metode ini selama bertahun-tahun berurusan dengan perubahan spesifikasi dan memperbaiki bug, dan akhirnya Anda berakhir dengan metode yang tidak mengurutkan daftar dan melempar pengecualian ketika menemukan fitur kosong. Jadi komentar di atas adalah komentar usang yang pada akhirnya akan membebani Anda waktu dalam debugger. Ini memang terjadi di beberapa basis kode.

Tanyakan pada diri sendiri ini Pernahkah Anda mengubah sebaris kode dan tidak mengubah komentar terkait atau menambahkan yang baru?

Saya telah bekerja dengan banyak kode lawas dan komentarnya kadang-kadang tidak mendekati yang relevan.

Sebagian besar, pengalaman saya cocok dengan Anda, tetapi saya telah menemukan satu kasus di mana itu benar di seluruh basis kode. Itu adalah aplikasi yang telah ditulis bertahun-tahun sebelumnya oleh toko konsultan yang tidak lagi "berhubungan baik" dengan klien.

Perusahaan melakukan pekerjaan luar biasa mengomentari kode, tetapi programmer yang mempertahankannya sejak handoff asli adalah bagian dari pola pikir "hanya mengubah apa yang benar-benar perlu diubah" yang dengan sendirinya tidak buruk. Sayangnya, mereka menjaga sikap yang sama terhadap komentar, yang mengarah ke pemutusan yang cukup besar antara komentar dan kode dari waktu ke waktu.

Saya tidak melihat terlalu banyak komentar deskriptif yang ketinggalan zaman, tetapi saya melihat banyak komentar TODO yang telah ada selama bertahun-tahun. Saya berharap mereka seperti kapsul waktu dan mengatakan sesuatu seperti ini:

//TODO: In 15 years AND NO SOONER... actually implement this method.

3 proyek terakhir yang saya kerjakan. Saya menghabiskan beberapa hari untuk masing-masing menghapus komentar usang, menyesatkan, dan hanya berguna dari basis kode. Bila mungkin dan perlu, saya menggantinya dengan komentar yang lebih tepat, tetapi lebih sering daripada tidak, itu hanya pertanyaan menghapus komentar dan melanjutkan.

Saya telah melakukan hal yang sama pada hampir semua basis kode yang pernah saya ambil dari orang lain, biasanya setelah itu tidak dipelihara untuk sementara waktu dan pemilik aslinya telah lama pergi dan / atau tidak mau atau tidak mampu melakukan penyerahan yang tepat.

Bisa jadi itu adalah penurunan dalam penggunaan komentar. Berapa banyak kode siapa pun yang memenuhi syarat? Untuk satu, seseorang benar-benar harus memasukkan komentar untuk menjadi ketinggalan zaman Kedua, kode yang dikomentari harus diubah. Tidak yakin persentase tinggi kode memenuhi syarat.

Anda hanya perlu mengandalkan satu komentar buruk untuk merusak sebagian besar aplikasi dan menghabiskan banyak waktu Anda.

Dalam organisasi yang mengeluarkan banyak kode, sulit untuk menjaga komentar tetap sinkron. Cara terbaik untuk memahami apa yang terjadi adalah dengan menggunakan perangkat lunak yang menggambar diagram alir kontrol dari modul yang sedang Anda kerjakan. Itulah satu-satunya cara untuk tetap merasakan apa yang dilakukan perangkat lunak.