Haruskah komentar Javadoc ditambahkan ke implementasi?

Apakah praktik yang benar untuk menambahkan komentar Javadoc di antarmuka dan menambahkan komentar non-Javadoc dalam implementasi?

Kebanyakan IDE menghasilkan komentar non-JavaDoc untuk implementasi ketika Anda membuat komentar secara otomatis. Bukankah metode konkret harus memiliki deskripsi?

Untuk metode yang hanya implementasi (bukan menimpa), tentu, mengapa tidak, terutama jika bersifat publik.

Jika Anda memiliki situasi yang berlebihan dan Anda akan mereplikasi teks apa pun, maka jelas tidak. Replikasi adalah cara jitu untuk menyebabkan ketidaksesuaian. Akibatnya, pengguna akan memiliki pemahaman yang berbeda tentang metode Anda berdasarkan apakah mereka memeriksa metode dalam supertipe atau subtipe. Gunakan @inheritDocatau jangan berikan dokumentasi - IDE akan menggunakan teks terendah yang tersedia untuk digunakan dalam tampilan Javadoc mereka.

Selain itu, jika versi pengganti Anda menambahkan sesuatu ke dokumentasi supertipe, Anda bisa berada dalam dunia yang bermasalah. Saya mempelajari masalah ini selama PhD saya dan menemukan bahwa secara umum orang tidak akan pernah mengetahui informasi tambahan dalam versi utama jika mereka memanggil melalui supertipe.

Mengatasi masalah ini adalah salah satu fitur utama dari alat prototipe yang saya buat - Setiap kali Anda menggunakan metode, Anda mendapat indikasi jika targetnya atau target utama yang potensial berisi informasi penting (misalnya, perilaku yang bertentangan). Misalnya, saat meminta put pada peta, Anda diingatkan bahwa jika implementasi Anda adalah TreeMap, elemen Anda harus sebanding.

Baik implementasi maupun antarmukanya harus memiliki javadoc. Dengan beberapa alat, Anda dapat mewarisi dokumentasi antarmuka dengan kata kunci @inheritDoc.

/**
 * @inheritDoc
 *
 * This implementation is very slow when b equals 3.
 */
public foo(int b)
{ ... }

Sedikit praktik yang baik untuk dilakukan

/**
 * {@inheritDoc}
 */

sebagai javadoc implementasi (kecuali jika ada hal tambahan yang perlu dijelaskan tentang detail implementasi).

Umumnya, saat Anda mengganti metode, Anda mematuhi kontrak yang ditentukan di kelas / antarmuka dasar, jadi Anda tidak ingin mengubah javadoc asli. Oleh karena itu penggunaan @inheritDocatau @seetag yang disebutkan dalam jawaban lain tidak diperlukan dan sebenarnya hanya berfungsi sebagai noise dalam kode. Semua alat yang masuk akal mewarisi metode javadoc dari superclass atau antarmuka seperti yang ditentukan di sini :

Inherit from classes and interfaces - Inheriting of comments occurs in all
three possible cases of inheritance from classes and interfaces:

- When a method in a class overrides a method in a superclass
- When a method in an interface overrides a method in a superinterface
- When a method in a class implements a method in an interface

Fakta bahwa beberapa alat (saya melihat Anda, Eclipse!) Menghasilkan ini secara default saat mengganti metode hanyalah keadaan yang menyedihkan, tetapi tidak membenarkan mengacaukan kode Anda dengan kebisingan yang tidak berguna.

Tentu saja ada kasus sebaliknya, ketika Anda benar-benar ingin menambahkan komentar ke metode penggantian (biasanya beberapa detail implementasi tambahan atau membuat kontrak sedikit lebih ketat). Tetapi dalam kasus ini, Anda hampir tidak pernah ingin melakukan sesuatu seperti ini:

/**
 * {@inheritDoc}
 *
 * This implementation is very, very slow when b equals 3.
 */

Mengapa? Karena komentar yang diwariskan mungkin bisa sangat panjang. Jika demikian, siapa yang akan melihat kalimat tambahan di akhir 3 paragraf panjang ?? Sebaliknya, tulis saja bagian dari komentar Anda sendiri dan itu saja. Semua alat javadoc selalu menampilkan beberapa jenis tautan Ditentukan oleh yang dapat Anda klik untuk membaca komentar kelas dasar. Tidak ada gunanya mencampurkannya.

@see Ini menghasilkan tautan ke deskripsi di antarmuka. Tapi menurut saya bagus juga untuk menambahkan beberapa detail tentang implementasinya juga.

Sjoerd dengan tepat mengatakan bahwa antarmuka dan implementasi harus memiliki JavaDoc. Antarmuka JavaDoc harus menentukan kontrak metode - metode apa yang harus dilakukan, input apa yang diperlukan, nilai apa yang harus dikembalikan, dan apa yang harus dilakukan jika terjadi kesalahan.

Dokumentasi implementasi harus mencatat perpanjangan atau batasan pada kontrak, dan juga rincian implementasi yang sesuai, terutama kinerja.

Demi menghasilkan javadoc ya itu penting. Jika Anda mendeklarasikan referensi ke implementasi konkret hanya dengan menggunakan antarmuka maka tidak karena metode antarmuka akan diambil oleh IDE.