Saya ingin menulis Javadoc dengan cara KERING. Tetapi dokumen oracle tentang Javadoc mengatakan menulis hal yang sama lagi dalam komentar metode overload. Bisakah saya menghindari pengulangan?
Saya ingin menulis Javadoc dengan cara KERING. Tetapi dokumen oracle tentang Javadoc mengatakan menulis hal yang sama lagi dalam komentar metode overload. Bisakah saya menghindari pengulangan?
Jawaban:
Saya memercikkan {@inheritDoc}arahan di sana-sini dalam komentar Javadoc saya ketika mengganti metode dari superclasses atau mengimplementasikan metode yang ditentukan antarmuka.
Ini berfungsi dengan baik bagi saya setidaknya, menghindari pengulangan dalam kode sumber, dan Anda masih dapat menambahkan informasi spesifik ke komentar Javadoc tertentu jika ada kebutuhan untuk melakukannya. Saya tidak mempertimbangkan fakta bahwa komentar Javadoc itu sendiri cukup sederhana untuk menjadi masalah ketika semua yang diperlukan dalam IDE yang layak adalah mengarahkan kursor ke nama pengenal terkait untuk mendapatkan Javadoc yang diberikan dengan referensi dan semuanya.
Maksud dokumentasi adalah untuk menerangi pengguna item yang akan datang. Ini sebagian untuk kenyamanan penulis, sehingga ia tidak perlu dihubungi setiap kali seseorang tidak dapat menemukan cara kerjanya. Namun, sebagian besar demi kepentingan orang-orang yang perlu menggunakan atau mendukung hal itu.
Dengan demikian, intinya harus jelas, sebagai lawan kenyamanan bagi penulis. Anda tidak dapat mengharapkan orang untuk naik turun melalui dokumentasi API Anda karena pada dasarnya Anda terlalu malas untuk mengulangi sendiri. Mengisapnya - Javadoc akan berulang.
Yang mengatakan, tidak ada alasan, jika Anda pintar, Anda tidak dapat menulis sebuah program yang akan menempel komentar ke dalam kode Anda berdasarkan spidol atau kriteria lainnya. Mungkin lebih banyak masalah daripada nilainya. Atau tidak.