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.