Apa pendekatan terbaik untuk komentar kode inline?

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?

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:

Saya katakan untuk alasan pemeliharaan, penting untuk mengetahui kapan dan siapa yang melakukan perubahan (bahkan informasi ini ada di SCM).

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.

Kode memiliki kehidupan karena itu memiliki sejarah.

Riwayat disimpan dalam kontrol sumber.
Anda juga percaya bahwa komentar itu ditulis oleh orang itu. Howkomentar 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.

Karena tanpa tanggal perubahan, tidak mungkin untuk mengetahui kapan perubahan diperkenalkan tanpa membuka alat SCM dan mencari dalam sejarah objek panjang.

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.

karena penulis sangat penting, perubahan authorx lebih kredibel daripada perubahan authory

Semua penulis (selain Anda sendiri) memiliki kredibilitas yang sama.

Alasan kelincahan, tidak perlu membuka alat SCM

Jika alat kontrol sumber Anda membebani Anda dengan salah menggunakannya atau (lebih mungkin) Anda menggunakan seperangkat alat yang salah untuk mengakses sistem kontrol sumber.

orang akan takut mengubah sesuatu yang dilakukan seseorang 15 tahun yang lalu, daripada sesuatu yang dibuat secara ...

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.

Sejarahnya ada di SCM

Iya. Alasan terbaik.

Pengembang tidak boleh mengetahui riwayat kode secara langsung dalam kode

Jika saya benar-benar membutuhkan informasi ini, saya akan mencarinya di kontrol sumber.
Kalau tidak, itu tidak relevan.

Paket mendapatkan garis 15k dan komentar tidak terstruktur yang sulit dipahami oleh paket ini

Komentar harus menjadi deskripsi mengapa Anda melakukan sesuatu.
Komentar TIDAK boleh menggambarkan cara kerja kode (kecuali algoritme tidak jelas).

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 ;-)