Kami sedang melakukan refactoring ke basis kode lama 20 tahun, dan saya sedang berdiskusi dengan rekan saya tentang format komentar dalam kode (plsql, java).
Tidak ada format default untuk komentar, tetapi dalam kebanyakan kasus orang melakukan sesuatu seperti ini di komentar:
// date (year, year-month, yyyy-mm-dd, dd/mm/yyyy), (author id, author name, author nickname) and comment
format yang diusulkan untuk komentar masa depan dan masa lalu yang saya inginkan adalah:
// {yyyy-mm-dd}, unique_author_company_id, comment
Rekan saya mengatakan bahwa kita hanya perlu komentar, dan harus memformat ulang semua komentar masa lalu dan masa depan ke format ini:
// comment
Argumen saya:
- Saya katakan untuk alasan pemeliharaan, penting untuk mengetahui kapan dan siapa yang melakukan perubahan (bahkan informasi ini ada di SCM).
- Kode itu hidup, dan karena itu memiliki sejarah.
- Karena tanpa tanggal perubahan, tidak mungkin untuk mengetahui kapan perubahan diperkenalkan tanpa membuka alat SCM dan mencari dalam sejarah objek panjang.
- karena penulis sangat penting, perubahan penulis lebih kredibel daripada perubahan penulis
- Alasan kelincahan, tidak perlu membuka dan menavigasi melalui alat SCM
- orang akan lebih takut untuk mengubah sesuatu yang dilakukan seseorang 15 tahun yang lalu, daripada sesuatu yang baru saja dibuat atau diubah.
- dll.
Argumen kolega saya:
- Sejarahnya ada di SCM
- Pengembang harus tidak menyadari sejarah kode secara langsung dalam kode
- Paket mendapatkan garis 15k panjang dan komentar yang tidak terstruktur membuat paket ini lebih sulit untuk dipahami
Menurut Anda apa pendekatan terbaik? Atau apakah Anda memiliki pendekatan yang lebih baik untuk menyelesaikan masalah ini?
java
c#
programming-practices
code-quality
comments
Diego Alvarez
sumber
sumber
Jawaban:
Komentar umum
Saya sangat percaya pada komentar adalah mengapa (bukan bagaimana) . Ketika Anda mulai menambahkan komentar tentang bagaimana Anda jatuh ke dalam masalah yang tidak ada yang menegakkan bahwa komentar dipertahankan dalam kaitannya dengan kode ( alasan mengapa biasanya tidak akan berubah (penjelasan mengapa dapat ditingkatkan beberapa kali).
Dengan cara yang sama date / authorInfo tidak memberi Anda apa pun dalam hal mengapa kode itu dilakukan dengan cara ini; sama seperti bagaimana itu dapat merosot dari waktu ke waktu karena tidak ada penegakan oleh alat apa pun. Juga informasi yang sama sudah disimpan dalam sistem kontrol sumber (sehingga Anda menduplikasi upaya (tetapi dengan cara yang kurang dapat diandalkan)).
Melewati argumen:
Mengapa. Tak satu pun dari hal-hal ini menurut saya penting untuk menjaga kode. Jika Anda perlu berbicara dengan penulis, relatif mudah untuk menemukan informasi ini dari kontrol sumber.
Riwayat disimpan dalam kontrol sumber.
Anda juga percaya bahwa komentar itu ditulis oleh orang itu.
How
komentar cenderung menurun seiring waktu sehingga sejarah semacam ini menjadi tidak dapat diandalkan. Sistem kontrol sumber di sisi lain akan mempertahankan riwayat yang sangat akurat dan Anda dapat secara akurat melihat kapan komentar ditambahkan / dihapus.Jika Anda mempercayai data dalam komentar.
Salah satu masalah dengan hal-hal semacam ini adalah bahwa komentar menjadi salah dalam kaitannya dengan kode. Kembali ke alat yang benar untuk pekerjaan itu. Sistem kontrol sumber akan melakukan ini dengan benar tanpa perlu intervensi dari pengguna. Jika sistem kontrol sumber Anda menyebalkan, maka mungkin Anda perlu mempelajari cara menggunakannya secara lebih tepat (karena fungsi itu biasanya mudah) atau jika tidak mendukungnya, temukan sistem kontrol sumber yang lebih baik.
Semua penulis (selain Anda sendiri) memiliki kredibilitas yang sama.
Jika alat kontrol sumber Anda membebani Anda dengan salah menggunakannya atau (lebih mungkin) Anda menggunakan seperangkat alat yang salah untuk mengakses sistem kontrol sumber.
Jika kode telah bertahan 15 tahun maka kemungkinan besar akan lebih solid maka kode yang hanya bertahan 6 bulan tanpa perlu ditinjau. Kode yang stabil cenderung tetap stabil, kode kereta cenderung menjadi lebih kompleks dari waktu ke waktu (karena alasannya kereta adalah masalahnya tidak sesederhana pemikiran pertama).
Semakin banyak alasan untuk menggunakan kontrol sumber untuk mendapatkan informasi.
Iya. Alasan terbaik.
Jika saya benar-benar membutuhkan informasi ini, saya akan mencarinya di kontrol sumber.
Kalau tidak, itu tidak relevan.
Komentar harus menjadi deskripsi mengapa Anda melakukan sesuatu.
Komentar TIDAK boleh menggambarkan cara kerja kode (kecuali algoritme tidak jelas).
sumber
Saya sangat mendukung rekan Anda. Anda tidak akan bertahan tanpa melihat SCM pula jika Anda ingin memahami mengapa sesuatu diubah kecuali Anda menyimpan kode lama dalam komentar.
Jika kode terlalu rumit untuk dipahami tanpa menulis banyak komentar, saya sarankan Anda menginvestasikan energi Anda ke dalam refactoring untuk membuat kode dapat dibaca / dikelola tanpa banyak komentar.
Lagi pula, Anda merekrut programmer, bukan tukang cerita ;-)
sumber