Komentar Pengambil / Penyetel Sederhana


125

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?


54
Sebagai tambahan, tolong jangan gunakan float untuk uang apa pun (seperti gaji di sini), selamanya. Lihat misalnya stackoverflow.com/questions/965831/…
Jonik

3
Gunakan BigDecimal sebagai gantinya.
Josep

Jawaban:


84

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.


Bisakah Anda memperbaiki kesalahan ketik? "@return bagian untuk setter"
Jonik

1
Ada juga kesalahan ketik dalam komentar gaji (). Ini bukan komentar JavaDoc.
Fostah

1
Saya setuju bahwa ini adalah pendekatan terbaik untuk mengomentari pengakses.
Fostah

31
Menambahkan derau ke kode Anda demi membungkam peringatan yang terlalu berlebihan dari alat kami terasa salah bagi saya. Jika itu tidak menambah nilai bagi seorang programmer, maka solusi yang tepat adalah dengan menolak / memperbaiki verbositas alat dan / atau mengurangi seberapa besar kita peduli untuk melompati rintangan sehingga alat itu memberi penghargaan kepada kita. Alat analisis seharusnya membantu kita dan menghemat tenaga, bukan membuat tugas yang lebih tidak masuk akal bagi kita.
Lyle

1
@Lyle Itu mungkin benar, tetapi saya merasa hampir selalu ada sesuatu yang berguna yang dapat dikatakan programmer yang menggambarkan pengambil / penyetel lebih baik daripada hanya metode tanda tangan saja. Ya, ada kasus di mana seorang programmer malas dan hanya mengulangi tanda tangan metode di komentar, tetapi saya pikir secara umum, ini adalah perilaku yang membantu untuk dipaksakan.
Matt Vukas

174

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.


2
Persis saya, yang terburuk adalah model spesifik domain di mana hanya ahli domain yang tahu apa arti properti itu.
ThaDon

7
Meskipun berguna, apa yang akan Anda lakukan untuk getFoo (). Apakah Anda juga akan menyalin komentar yang sama untuk getFoo ()?
Vinoth Kumar CM

3
@cmv: Jelas bagian "param" tidak akan disalin. Saya ragu-ragu apakah nilai memiliki informasi yang dilampirkan ke kedua pengakses secara langsung membenarkan penggandaan informasi. Mungkin iya. Lebih baik lagi jika Anda melampirkan satu komentar ke keduanya; Saya yakin ini tersedia di Project Lombok.
Michael Borgwardt

@VinothKumar: mungkin akan lebih baik jika menjelaskan properti di pengambil (seperti dalam "Foo adalah faktor penyesuaian yang digunakan dalam kalkulasi Batang.") Dan efek perubahan nilai dalam penyetel (atau apakah perlu atau tidak untuk menginisialisasi nilai itu - dalam contoh jawaban tidak perlu menginisialisasi Foo karena "ini memiliki nilai default tergantung pada jenis Baz").
freitas

+1 untuk "nama tidak jelas yang hanya dipahami oleh bankir investasi, ahli biokimia, atau fisikawan kuantum"
Jackson

36

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.


5
Jawaban lain yang valid di sepanjang baris ini mungkin "desain dengan getter dan setter tidak benar-benar memahami pengertian enkapsulasi" :)
Trejkaz

2
@Trejkaz: Tidak benar, karena metode pengakses memungkinkan untuk properti hanya-baca atau hanya-tulis, dan untuk polimorfisme (dan juga pembungkusan, proksi, dan sebagainya).
Laurent Pireyn

2
Mereka mungkin mengizinkan hal-hal itu, tetapi seringkali pola pembangun dapat menggantikan penyetel (kurang bisa berubah) atau pola pengunjung dapat menggantikan getter (lebih fleksibel.)
Trejkaz

Saya pasti suka dan menggunakan pola pembangun, tetapi ada begitu banyak dukungan untuk POJO (misalnya dalam Hibernate) sehingga pengambil dan penyetel masih memiliki tempat yang sangat menonjol, baik atau buruk. Ini adalah hal paling menarik tentang Java, IMHO, dan setelah menulis JavaDocs yang berulang selama lebih dari satu dekade, saya siap untuk berlangganan saran @ sleske.
Michael Scheper

34

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]


10
boleh dibilang, sebaiknya ganti nama getter yang memiliki efek samping menjadi lebih jelas, karena tidak semua developer akan membaca komentar tersebut.
akf

Tidak apa-apa - tetapi itu mengharuskan pengguna API Anda untuk mengetahui bahwa, seandainya ada efek samping, mereka akan didokumentasikan !
oxbow_lakes

akf, saya berpikir persis seperti itu setelah memposting :) Saya rasa saya akan menambahkannya ke tanggapan saya.
Gopherkhan

1
tetapi jika Anda tidak mendokumentasikan getter dan setter yang "bodoh" (itu yang saya juga lebih suka!) - bagaimana Anda menyingkirkan peringatan Eclipse pada javadoc yang hilang? Saya tidak ingin mengacaukan ruang kerja saya dengan peringatan seperti itu, tetapi saya juga tidak ingin peringatan itu dinonaktifkan untuk semua metode lain ...
Zordid

12

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.


1
sementara saya setuju dengan Anda, saya pikir seseorang harus memastikan bahwa komentar fungsi tidak mencari nama fungsi non-eksplisit yang dipilih dengan buruk.
karlipoppins

Saya adalah pendukung besar JavaDocs, tetapi juga pendukung besar kode dokumentasi mandiri. Jadi setidaknya untuk setter, saya akan melakukan sesuatu seperti public void setSalary(float aud)(atau lebih realistis, public void setSalary(BigDecimal aud)). Lebih baik lagi, properti itu harus berjenis abstract class CurrencyAmount, yang pada gilirannya memiliki properti java.util.Currency currencydan java.math.BigDecimal amount. Sebagian besar pengembang yang pernah bekerja dengan saya sangat malas dengan JavaDoc, tetapi menerapkan API seperti ini membuat masalah ini berkurang.
Michael Scheper

Jika satuannya adalah satuan SI seperti meter / detik, maka perlu didokumentasikan, jika bukan satuan Si maka harus didokumentasikan atau lebih baik dinamai dengan menyertakan satuan non standar, misalnya heightFeet
AlexWien

8

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).


Saya setuju. Dan kemudian saya menyadari, mengapa menulis semua boilerplate ini? Lihat jawaban saya tentang Project Lombok.
Michael Scheper

7

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 .


4

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.


11
Tanpa dokumentasi, setiap pemanggil akan berasumsi bahwa metode yang disebut setX menyetel X. Oleh karena itu, jika setX benar-benar menyetel X, tanpa melakukan hal lain yang penting, Anda tidak memerlukan dokumentasi.
mqp

Itu hebat! Sekarang apakah perusahaan CrudTech ini, yang API-nya saya kodekan, mengikuti konvensi Anda, atau mengikuti konvensi orang lain di utas ini? Hmmmm
oxbow_lakes

5
Tidak ada gunanya menulis "set harga" di dokumen setPrice jika metode tersebut hanya menyetel nilai untuk properti price, tetapi jika metode tersebut juga misalnya memperbarui properti totalPrice dan menghitung ulang pajak, perilaku tersebut harus didokumentasikan dengan jelas.
João Marcus

8
Anda tampaknya meminta dokumentasi untuk menyatakan "Ini melakukan apa yang Anda harapkan." Yang seperti menulis "Perhatian: PANAS" di atas secangkir kopi. Di dunia yang sempurna, tidak perlu pernah mengatakan hal-hal seperti itu.
Kevin Panko

1
Ya - setelah menggunakan API di mana metode yang disebut hal-hal seperti setXmemiliki efek samping selain yang diharapkan, saya memang dapat menyatakan dengan keyakinan bahwa ini bukanlah dunia yang sempurna.
oxbow_lakes

4

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();

2
Masalah dengan pendekatan ini adalah Javadoc tidak menghasilkan dokumentasi pribadi secara default! Jika demikian, tag referensi {@see #salary}tidak valid dalam dokumentasi yang dibuat.
Jarek Przygódzki

1

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?


6
Bagaimana jika getFirstName () mengembalikan null? Dimana itu akan didokumentasikan?
Steve Kuo

Bagaimana dengan security.getFinalMaturity ()? Tidak semua nama properti memiliki arti yang langsung bisa dimengerti. Apakah Anda ingin dipecat karena tidak tahu apa artinya?
Michael Borgwardt

Bagaimana jika metode tersebut diterapkan dengan swizzling? Bagaimana Anda bisa tahu itu kecuali sudah didokumentasikan dengan jelas? Bagaimana Anda bisa tahu ini adalah penyetel standar kecuali dokter mengatakannya?
oxbow_lakes

2
get / set harus menurut pendapat saya disediakan untuk getter dan setter. Pencarian database harus diberi nama seperti "lookupPerson" atau lebih.
Thorbjørn Ravn Andersen

1

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.


1
Ada perbedaan antara berkomentar dan mendokumentasikan.
Tom Hawtin - tackline

1
Sangat benar. Karena itu tepatnya mengapa saya tidak berkomentar getter dan setter. Mereka harus cukup jelas, dan menambahkan komentar menunjukkan bahwa kode tersebut tidak cukup jelas.
Thorbjørn Ravn Andersen

0

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


Tidak bagus - orang tidak membaca kolom komentar. Javadoc bahkan tidak membuat dokumentasi pribadi secara default, dan IDE tidak menampilkan dokumentasi lapangan saat Anda menggunakan bantuan cepat pada panggilan metode.
Trejkaz

orang tidak membaca kolom komentar kecuali mereka perlu. Begitu ada kebutuhan, semakin banyak informasi semakin baik.
akf

0

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


0

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


Mereka hanya cukup menjelaskan jika Anda mengatakan "ini adalah penyetel properti". Jika klien API tidak tahu apa pun yang sebenarnya terjadi di dalam metode
oxbow_lakes

1
Siapa yang mengatakan sesuatu tentang penjelasan diri sendiri?
Paul Sonier
Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.