Menulis dokumentasi untuk metode yang dipahami dengan baik sama dengan di Jawa

Apakah praktik yang baik untuk menulis komentar untuk metode yang dikenal luas seperti equals, compareTo dll?

Pertimbangkan kode di bawah ini.

 /**
 * This method compares the equality of the current object 
  with the object of same type
 */
@Override
public boolean equals(Object obj) {

               //code for equals

     }   

Perusahaan saya ingin memasukkan komentar seperti di atas. Apakah diperlukan komentar Javadoc di atas? Apakah tidak jelas dan dipahami dengan baik apa yang sama dengan metode dan suka (bandingkan, bandingkan dengan) dll tidak?

Apa saran Anda?

JavaDoc sudah mendukung pewarisan komentar . Menurut dokumentasi, "konstruktor, bidang dan kelas bersarang tidak mewarisi komentar dokumen", tetapi metode seperti equals()akan. Karena Objectkelas memiliki equals()metode yang terdokumentasi dengan baik , Anda seharusnya bisa mewarisi dokumentasi itu tanpa masalah.

Dokumentasi untuk metode ini harus berasal dari suatu tempat sehingga dapat diakses di IDE Anda dan di dokumentasi web yang dihasilkan. Secara eksplisit menulis ulang komentar yang akurat dan komprehensif yang ada dalam superclass tidak diperlukan, dan saya akan berdebat mengacaukan file kode.

Jika ini adalah kebijakan perusahaan, maka Anda memiliki dua opsi. Anda dapat melakukannya dengan lamban, dan berurusan dengan upaya ekstra untuk menulis dan memelihara dokumentasi (sering kali melanggar prinsip KERING, yang juga dapat diterapkan pada dokumen dan kode). Pilihan lain adalah mencari kebijakan perusahaan - jelaskan mengapa kebijakan ini bukan ide yang baik dan manfaat mengubahnya (dalam hal waktu, uang, usaha, kualitas - hal-hal yang dipahami manajemen).

Di tim saya, kami biasanya menggunakan @inheritDocanotasi untuk equals()dan hashcode()tetapi saya berharap kami tidak melakukannya.

Untuk dua metode ini saya selalu harus melihat implementasinya. Karena Anda mengganti metode, itu berarti Anda ingin melakukan sesuatu yang berbeda. Saya pikir ini layak untuk didokumentasikan sendiri.

Adalah baik untuk setidaknya mendokumentasikan atribut apa yang berpartisipasi dalam metode ini dan bahkan mungkin mengapa demikian.

Ingat bahwa komentar membantu semua jenis pengembang jika benar.

Masalahnya adalah mereka terkadang tidak lengkap dan tidak akurat.

Jujur membandingkan 2 objek mungkin rumit (misalnya membandingkan 2 objek faktur), juga metode Anda dapat berkembang dengan waktu dan kemudian perlu dikomentari.

Menampilkan metode objektif, aturan, dll dalam komentar "berguna dan bermakna" adalah hal yang baik.

Merupakan praktik yang sangat buruk untuk membuang kode dengan komentar kosong seperti:

/**
 * This method compares the equality of the current object with the object of same type...
 */

Ini mengatakan tidak ada yang berguna. Lebih buruk lagi, buruk dalam gaya dan tata bahasa:

1. Komentar tidak boleh dimulai dengan "Metode ini" atau "Kelas ini" atau "Ini" apa saja. Komentar tersebut dikaitkan dengan metode atau kelas berdasarkan lokasinya di file sumber.

2. "objek" harus membaca "objek"

3. "Membandingkan kesetaraan" hanya masuk akal jika satu objek dapat memiliki lebih banyak "kesetaraan" daripada yang lain. Fungsi ini tidak membandingkan "kesetaraan"; itu membandingkan objek untuk menentukan kesetaraan mereka satu sama lain.

Sebagai gantinya, komentar harus menunjukkan kapan kedua objek dianggap sama. Di sini, saya akan menghilangkan deskripsi metode sepenuhnya, dan hanya mendokumentasikan nilai pengembalian, misalnya:

public class Fraction {
  private int numerator, denominator;
  /**
   * @return true if <i>this</i> is numerically equal to <i>other</i>
   */
  public boolean equals(Fraction other) {
    return numerator * other.denominator == other.numerator * denominator;
  }
...
}

Komentar yang dihasilkan untuk metode get / set sepele adalah yang terburuk dari semua.

Standar pengkodean kami menentukan bahwa ketika mengganti metode, tidak perlu mendokumentasikannya kecuali, dalam menimpanya, dokumentasi di kelas atau antarmuka induk tidak lagi akurat dan komprehensif untuk kelas sub atau kelas implementasi.

Untuk equals, kami mungkin ingin mencatat bahwa perbandingan hanya dilakukan pada kunci utama ketika membandingkan entitas yang didukung database karena itu tidak sepenuhnya konsisten dengan dokumentasi untuk Object.equals().

Menurut pendapat saya, dan saya pikir ini mungkin kontroversial, Anda harus menunjukkan dalam komentar di kelas mana Anda telah menimpa kelas tersebut. Kemudian enam bulan kemudian ketika Anda bertanya-tanya apakah itu diterapkan atau tidak, Anda akan dapat melihat tanpa membuka kelas.

Mengetahui bahwa metode-metode itu umum dan sebagian besar pengembang akan tahu untuk apa itu, IMO, Anda tidak perlu memberikan komentar di sana. Komentar tidak dapat diandalkan dalam jangka panjang karena ada kemungkinan ini tidak akan diperbarui ketika implementasi diperbarui dan dapat menyebabkan kebingungan. Jadi selalu lebih baik untuk membuat kode Anda dapat dibaca karena ini adalah apa yang sebagian besar dapat Anda percayai.

Lebih lanjut, saya akan mengatakan bahwa jika kode yang Anda buat / edit bukan untuk API publik maka tinggalkan javadocs untuk metode umum karena ini hanya akan menambah kekacauan dan kebisingan.