Komentar Pengambil / Penyetel Sederhana

Konvensi apa yang Anda gunakan untuk pengambil dan penyetel komentar? Ini adalah sesuatu yang saya pikirkan selama beberapa waktu, misalnya:

/**
 * (1a) what do you put here?
 * @param salary (1b) what do you put here?
 */
public void setSalary(float salary);

/*
 * (2a) what do you put here?
 * @return (2b)
 */
public float getSalary();

Saya selalu menemukan saya cukup banyak menulis hal yang persis sama untuk 1a / b dan 2a / b, seperti 1a) Menetapkan gaji karyawan, 1b) gaji karyawan. Sepertinya terlalu berlebihan. Sekarang saya dapat melihat sesuatu yang lebih kompleks Anda mungkin menulis lebih banyak di bagian (a), untuk memberikan konteks, tetapi untuk mayoritas pengambil / penyetel di luar sana kata-katanya hampir persis sama.

Saya hanya ingin tahu apakah, untuk pengambil / penyetel sederhana tidak masalah untuk hanya mengisi bagian (a) ATAU bagian (b).

Bagaimana menurut anda?

Saya biasanya hanya mengisi bagian param untuk setter, dan bagian @return untuk getter:

/**
 * 
 * @param salary salary to set (in cents)
 */
public void setSalary(float salary);

/**
 * @return current salary (in cents, may be imaginary for weird employees)
 */
public float getSalary();

Dengan begitu, alat pemeriksaan javadoc (seperti peringatan Eclipse) akan keluar dengan bersih, dan tidak ada duplikasi.

Sama sekali tidak ada gunanya - Anda lebih baik tanpa omong kosong semacam ini yang mengacaukan kode Anda:

/**
 * Sets the foo.
 * 
 * @param foo the foo to set
 */
public void setFoo(float foo);

Sangat berguna, jika diperlukan:

/**
 * Foo is the adjustment factor used in the Bar-calculation. It has a default
 * value depending on the Baz type, but can be adjusted on a per-case base.
 * 
 * @param foo must be greater than 0 and not greater than MAX_FOO.
 */
public void setFoo(float foo);

Terutama penjelasan tentang arti sebenarnya dari properti dapat menjadi sangat penting dalam model domain. Setiap kali saya melihat kacang penuh dengan properti dengan nama tidak jelas yang hanya dipahami oleh bankir investasi, ahli biokimia atau fisikawan kuantum, dan komentar menjelaskan bahwa metode setGobbledygook () "menetapkan gobbledygook.", Saya ingin mencekik seseorang.

Umumnya tidak ada, jika saya bisa membantu. Pemberi dan penyetel harus cukup jelas.

Saya tahu itu terdengar seperti non-jawaban, tapi saya mencoba menggunakan waktu saya untuk berkomentar hal-hal yang membutuhkan penjelasan.

Saya akan mengatakan hanya khawatir tentang memberi komentar getter dan setter jika mereka memiliki semacam efek samping, atau memerlukan semacam prasyarat di luar inisialisasi (yaitu: mendapatkan akan menghapus item dari struktur data, atau untuk mengatur sesuatu yang Anda butuhkan untuk menempatkan x dan y di tempat pertama). Kalau tidak, komentar di sini cukup berlebihan.

Sunting: Selain itu, jika Anda menemukan banyak efek samping yang terlibat dalam pengambil / penyetel, Anda mungkin ingin mengubah pengambil / penyetel agar memiliki nama metode yang berbeda (yaitu: push dan pop untuk tumpukan) [Terima kasih untuk komentar di bawah]

Tanyakan pada diri Anda apa yang Anda ingin orang lihat ketika komentar dilihat sebagai JavaDocs (dari browser). Banyak orang mengatakan bahwa dokumentasi tidak perlu karena sudah jelas. Ini tidak akan berlaku jika bidang tersebut bersifat pribadi (kecuali Anda secara eksplisit mengaktifkan JavaDocs untuk bidang pribadi).

Dalam kasus Anda:

public void setSalary(float s)
public float getSalary()

Tidak jelas berapa gaji yang dinyatakan. Apakah sen, dolar, pound, RMB?

Saat mendokumentasikan setter / getter, saya ingin memisahkan apa dari encoding. Contoh:

/**
 * Returns the height.
 * @return height in meters
 */
public double getHeight()

Baris pertama mengatakan itu mengembalikan ketinggian. Parameter kembali mendokumentasikan bahwa tinggi dalam meter.

Mengapa mereka tidak menyertakan tag referensi untuk memungkinkan Anda mengomentari nilai bidang dan referensi dari pengambil dan penyetel.

/**
* The adjustment factor for the bar calculation.
* @HasGetter
* @HasSetter
*/
private String foo;

public String getFoo() {
  return foo;
}

public void setFoo() {
  this foo = foo;
}

Sehingga dokumentasi berlaku untuk pengambil dan penyetel serta bidang (jika javadocs pribadi diaktifkan itu).

Jenis boilerplate ini dapat dihindari dengan menggunakan Project Lombok . Cukup dokumentasikan variabel bidang, meskipun itu private, dan biarkan anotasi Lombok menghasilkan pengambil dan penyetel yang terdokumentasi dengan benar.

Bagi saya, manfaat ini saja sepadan dengan biayanya .

Saya benar-benar kecewa dengan jawaban yang pada dasarnya mengatakan bahwa mendokumentasikan komprehensif adalah buang-buang waktu. Bagaimana klien API Anda seharusnya mengetahui bahwa metode yang dipanggil setXadalah penyetel properti JavaBean standar kecuali Anda mengatakannya dengan jelas dalam dokumentasi ?

Tanpa dokumentasi, penelepon tidak akan tahu sama sekali jika metode tersebut memiliki efek samping, selain dengan menyilangkan jari mereka tentang konvensi nyata yang diikuti.

Saya yakin saya bukan satu-satunya di sini yang mengalami kemalangan karena mengetahui cara sulit yang disebut metode setXmelakukan lebih dari sekadar menetapkan properti.

Jika tidak ada operasi khusus dalam pengambil / penyetel, saya biasanya menulis:

Dengan Javadoc (dengan opsi pribadi):

/** Set {@see #salary}. @param {@link #salary}. */
public void setSalary(float salary);

dan / atau

/** 
 * Get {@see #salary}.
 * @return {@link #salary}.
 */
public float salary();

Dengan Doxygen (dengan opsi ekstrak pribadi):

/** @param[in] #salary. */
public void setSalary(float salary);

/** @return #salary. */
public float salary();

Mengomentari pengakses, terutama jika mereka tidak melakukan operasi apa pun di mana pun, tidak diperlukan dan hanya membuang-buang ujung jari.

Jika seseorang yang membaca kode Anda tidak dapat memahami bahwa person.getFirstName()mengembalikan nama depan seseorang, Anda harus mencoba sekuat tenaga untuk membuatnya dipecat. Jika ia melakukan sihir database, melempar beberapa dadu, memanggil Sekretaris Nama Depan untuk mendapatkan nama depan, Aman untuk menganggap ini operasi non-sepele, dan mendokumentasikannya dengan baik.

Sebaliknya, jika Anda person.getFirstName()tidak mengembalikan nama depan seseorang ... yah, mari kita tidak pergi ke sana, oke?

Jangan masukkan apa pun jika nama bidang cukup mendeskripsikan konten.

Umumnya, biarkan kode berdiri sendiri, dan hindari berkomentar jika memungkinkan. Ini mungkin membutuhkan refactoring.

EDIT: Di atas mengacu pada getter dan setter saja. Saya percaya apa pun yang tidak sepele harus dijawab dengan benar.

Anda boleh mengisi bagian (b), terutama jika Anda memberi komentar pada deklarasi field yang menunjukkan tentang apa field itu.

Jika javadoc tidak menambahkan apapun, saya menghapus javadoc dan menggunakan komentar yang dibuat secara otomatis.

Saya selalu mengisi keduanya. Waktu tambahan yang dihabiskan untuk mengetik dapat diabaikan, dan lebih banyak informasi lebih baik daripada lebih sedikit, secara umum.