Apakah perlu untuk menulis komentar javadoc untuk setiap parameter dalam tanda tangan metode?

Salah satu devs di tim saya percaya bahwa perlu untuk menulis komentar javadoc untuk setiap parameter dalam tanda tangan metode. Saya tidak berpikir ini perlu, dan bahkan saya pikir itu bisa berbahaya.

Pertama, saya pikir nama parameter harus deskriptif dan mendokumentasikan diri. Jika tidak segera jelas untuk apa parameter Anda, Anda mungkin Melakukannya Salah. Namun, saya mengerti bahwa kadang-kadang tidak jelas untuk parameter apa, jadi dalam kasus itu, ya, Anda harus menulis komentar javadoc yang menjelaskan parameter.

Tapi saya pikir itu tidak perlu dilakukan untuk setiap parameter. Jika sudah jelas untuk parameter apa, komentar javadoc berlebihan; Anda hanya menciptakan pekerjaan ekstra untuk diri sendiri. Selain itu, Anda membuat pekerjaan ekstra untuk siapa saja yang harus menjaga kode Anda. Metode berubah dari waktu ke waktu, dan mempertahankan komentar hampir sama pentingnya dengan menjaga kode Anda. Berapa kali Anda melihat komentar seperti "X tidak Y karena alasan Z" hanya untuk melihat bahwa komentar tersebut sudah ketinggalan zaman, dan pada kenyataannya metode tersebut bahkan tidak mengambil parameter X lagi? Itu terjadi setiap saat, karena orang lupa memperbarui komentar. Saya berpendapat bahwa komentar yang menyesatkan lebih berbahaya daripada tidak ada komentar sama sekali. Dan dengan demikian adalah bahaya dari komentar berlebihan: dengan membuat dokumentasi yang tidak perlu, Anda

Namun, saya menghormati pengembang lain di tim saya, dan menerima bahwa mungkin dia benar dan saya salah. Itulah sebabnya saya membawa pertanyaan saya kepada Anda, sesama pengembang: Apakah memang perlu untuk menulis komentar javadoc untuk setiap parameter? Asumsikan di sini bahwa kode tersebut adalah internal perusahaan saya, dan tidak akan dikonsumsi oleh pihak luar mana pun.

Javadoc (dan, dalam kata Microsoft, XMLDoc) bukan komentar , mereka adalah dokumentasi .

Komentar bisa sangat jarang seperti yang Anda inginkan; dengan asumsi kode Anda setengah bisa dibaca, maka komentar biasa hanyalah rambu-rambu untuk membantu pengembang masa depan dalam memahami / mempertahankan kode yang sudah mereka tinjau selama dua jam.

The dokumentasi merupakan kontrak antara satu unit kode dan penelepon. Itu adalah bagian dari API publik. Selalu berasumsi bahwa Javadoc / XMLdoc akan berakhir dalam file bantuan atau dalam popup penyelesaian autocomplete / intellisense / kode, dan diamati oleh orang-orang yang tidak memeriksa internal kode Anda tetapi hanya ingin menggunakannya untuk beberapa tujuan mereka sendiri.

Nama argumen / parameter tidak pernah jelas. Anda selalu berpikir itu adalah ketika Anda menghabiskan hari terakhir mengerjakan kode, tetapi coba kembali ke sana setelah liburan 2 minggu dan Anda akan melihat betapa tidak membantu mereka sebenarnya.

Jangan salah paham dengan saya - penting untuk memilih nama yang bermakna untuk variabel dan argumen. Tapi itu adalah masalah kode, bukan masalah dokumentasi. Jangan menggunakan ungkapan "mendokumentasikan diri sendiri" secara harfiah; yang dimaksud dalam konteks dokumentasi internal (komentar), bukan dokumentasi eksternal (kontrak).

Entah mengomentari semuanya atau berkomentar apa-apa (jelas mengomentari semuanya adalah pilihan yang jauh lebih baik). Pikirkan tentang seseorang yang menggunakan kode Anda, baik meninjau API Anda langsung di file sumber Anda atau dalam file doc yang dihasilkan (yaitu keluaran doxygen). Ketidakkonsistenan pada umumnya menyebabkan kebingungan, yang mengarah pada waktu yang dihabiskan untuk menggali sumber untuk mencari tahu mengapa sesuatu tidak dikomentari, yang mengarah pada waktu yang terbuang yang bisa dihindari seandainya parameter baru saja dikomentari di tempat pertama.

Ingat: Sesuatu yang masuk akal bagi Anda dapat diartikan sepenuhnya berbeda oleh orang lain, tidak peduli seberapa biasa Anda memikirkannya (pikirkan tentang seseorang yang tidak sekuat bahasa Inggris dalam membaca dan mencoba memahami kode Anda).

Setelah mengatakan semua itu, jika pengembang lain menekankan pentingnya mendokumentasikan semuanya, maka sama pentingnya (jika tidak lebih) perlu dilakukan untuk menjaga agar dokumentasi tetap mutakhir. Seperti yang Anda nyatakan, tidak ada yang lebih buruk daripada memiliki komentar yang ketinggalan zaman (sama buruknya, jika tidak lebih buruk dari dokumen yang dihilangkan).

Mari kita mulai dari asumsi bahwa siklus pengembang adalah sumber daya yang kita coba untuk pelihara.

Jadi itu berarti bahwa pengembang seharusnya tidak membuang waktu untuk mendokumentasikan parameter yang jelas dan mengembalikan nilai, kan?

Baiklah, mari kita jabarkan.

Jika kita mendokumentasikan semuanya, menganggap komentar marjinal benar-benar sepele dan tidak memerlukan pemikiran atau penelitian, biaya adalah waktu tambahan untuk benar-benar mengetik komentar dan memperbaiki kesalahan ketik.

Jika kita memilih, maka biayanya adalah:

• Memiliki dan memenangkan argumen dengan pengembang lain di tim Anda yang berpikir semuanya harus didokumentasikan.
• Untuk setiap parameter, tentukan apakah ini harus atau tidak harus didokumentasikan.
• Lebih banyak argumen dengan tim Anda ketika seseorang memiliki pendapat berbeda tentang apakah suatu parameter seharusnya didokumentasikan.
• Menghabiskan waktu memburu kode dan meneliti ketika parameter yang dianggap cukup jelas ternyata tidak begitu.

Jadi, saya cenderung hanya mendokumentasikan semuanya. Kelemahan pasti, tetapi terkandung.

Jika Anda tetap menulis Javadoc, Anda sebaiknya menuliskannya sepenuhnya, bahkan termasuk parameter "jelas". Mereka mungkin jelas bagi Anda atau pengembang lain, tetapi siapa pun yang baru melihatnya akan mendapat manfaat dari mengetahui maksud dari setiap parameter.

Adapun untuk menjaga Javadoc dengan benar, Anda perlu menggunakan alat untuk pengembangan Anda yang membantu Anda dengan ini. Eclipse muncul di pikiran. Tentu saja, jika ini penting, Anda harus memastikan bahwa semua orang di tim melakukan bagian mereka untuk menjaga kode, termasuk komentar.

Jangan lupa bahwa javadoc dapat dibuat terlihat sementara terpisah dari kode, contoh utama adalah Java API itu sendiri. Dengan tidak memasukkan javadoc untuk setiap parameter dalam suatu metode, Anda salah mengartikan metode tersebut dan bagaimana cara menggunakannya.

'perlu' sepenuhnya subjektif. Saya pikir yang Anda tanyakan adalah, 'dalam situasi Anda, sebaiknya Anda menambahkan komentar javadoc'. Tidak mengetahui ruang lingkup atau konteks aplikasi Anda, bagaimana kami tahu apa yang sesuai untuk Anda?

Jika kode yang terbuka untuk umum ini (yaitu, kode yang dimaksudkan untuk diakses orang lain, seperti api) maka ya, dokumentasikan setiap parameter tunggal. Jangan menganggap pembaca tahu tentang proyek sebanyak yang Anda lakukan. Tetapi sebaliknya, terserah Anda dan tim Anda untuk membuat keputusan sendiri.