Apakah perlu untuk menulis komentar javadoc untuk setiap parameter dalam tanda tangan metode?


17

Salah satu devs di tim saya percaya bahwa perlu untuk menulis komentar javadoc untuk setiap parameter dalam tanda tangan metode. Saya tidak berpikir ini perlu, dan bahkan saya pikir itu bisa berbahaya.

Pertama, saya pikir nama parameter harus deskriptif dan mendokumentasikan diri. Jika tidak segera jelas untuk apa parameter Anda, Anda mungkin Melakukannya Salah. Namun, saya mengerti bahwa kadang-kadang tidak jelas untuk parameter apa, jadi dalam kasus itu, ya, Anda harus menulis komentar javadoc yang menjelaskan parameter.

Tapi saya pikir itu tidak perlu dilakukan untuk setiap parameter. Jika sudah jelas untuk parameter apa, komentar javadoc berlebihan; Anda hanya menciptakan pekerjaan ekstra untuk diri sendiri. Selain itu, Anda membuat pekerjaan ekstra untuk siapa saja yang harus menjaga kode Anda. Metode berubah dari waktu ke waktu, dan mempertahankan komentar hampir sama pentingnya dengan menjaga kode Anda. Berapa kali Anda melihat komentar seperti "X tidak Y karena alasan Z" hanya untuk melihat bahwa komentar tersebut sudah ketinggalan zaman, dan pada kenyataannya metode tersebut bahkan tidak mengambil parameter X lagi? Itu terjadi setiap saat, karena orang lupa memperbarui komentar. Saya berpendapat bahwa komentar yang menyesatkan lebih berbahaya daripada tidak ada komentar sama sekali. Dan dengan demikian adalah bahaya dari komentar berlebihan: dengan membuat dokumentasi yang tidak perlu, Anda

Namun, saya menghormati pengembang lain di tim saya, dan menerima bahwa mungkin dia benar dan saya salah. Itulah sebabnya saya membawa pertanyaan saya kepada Anda, sesama pengembang: Apakah memang perlu untuk menulis komentar javadoc untuk setiap parameter? Asumsikan di sini bahwa kode tersebut adalah internal perusahaan saya, dan tidak akan dikonsumsi oleh pihak luar mana pun.


Banyak Java IDEs (Intellij pada khususnya) akan menandai parameter Javadoc yang hilang sebagai peringatan dokumentasi
Gary Rowe

NetBeans dan Eclipse juga akan melakukannya.
Davor Ždralo

Jawaban:


38

Javadoc (dan, dalam kata Microsoft, XMLDoc) bukan komentar , mereka adalah dokumentasi .

Komentar bisa sangat jarang seperti yang Anda inginkan; dengan asumsi kode Anda setengah bisa dibaca, maka komentar biasa hanyalah rambu-rambu untuk membantu pengembang masa depan dalam memahami / mempertahankan kode yang sudah mereka tinjau selama dua jam.

The dokumentasi merupakan kontrak antara satu unit kode dan penelepon. Itu adalah bagian dari API publik. Selalu berasumsi bahwa Javadoc / XMLdoc akan berakhir dalam file bantuan atau dalam popup penyelesaian autocomplete / intellisense / kode, dan diamati oleh orang-orang yang tidak memeriksa internal kode Anda tetapi hanya ingin menggunakannya untuk beberapa tujuan mereka sendiri.

Nama argumen / parameter tidak pernah jelas. Anda selalu berpikir itu adalah ketika Anda menghabiskan hari terakhir mengerjakan kode, tetapi coba kembali ke sana setelah liburan 2 minggu dan Anda akan melihat betapa tidak membantu mereka sebenarnya.

Jangan salah paham dengan saya - penting untuk memilih nama yang bermakna untuk variabel dan argumen. Tapi itu adalah masalah kode, bukan masalah dokumentasi. Jangan menggunakan ungkapan "mendokumentasikan diri sendiri" secara harfiah; yang dimaksud dalam konteks dokumentasi internal (komentar), bukan dokumentasi eksternal (kontrak).


1
+1: Ini sama pentingnya dengan kode itu sendiri. Hanya saja tidak memiliki pengujian otomatis yang baik.
S.Lott

Jika parameter untuk suatu metode meliputi misalnya tiga pasangan koordinat X dan Y yang akan ditafsirkan sebagai sudut-sudut yang berdekatan dari jajaran genjang, apakah lebih bermanfaat untuk memiliki enam lembar dokumentasi, satu untuk setiap parameter, atau untuk menggambarkan tujuan dari metode dalam hal jajaran genjang (x1, y1), (x2, y2), (x3, y3), dan (x1 + x3-x2, y1 + y3-y2) [yang terakhir berlawanan (x2, y2)]? Jika tujuan dari metode ini didefinisikan dalam hal nama parameter, saya akan berpikir dokumentasi tambahan tentang parameter dalam banyak kasus akan berlebihan.
supercat

1
@ supercat: Saya berpendapat bahwa dalam kasus seperti itu, Anda harus melakukan refactoring, sehingga Anda memiliki tipe data tunggal Point,, dan fungsinya hanya membutuhkan tiga Points(atau lebih baik lagi sebuah array / iterable dari mereka). Semakin banyak parameter yang dimiliki metode, semakin sulit untuk dipanggil dan spesifikasinya cenderung tidak stabil seiring berjalannya waktu.
Aaronaught

@Aaronaught: Itu sangat tergantung pada bagaimana metode akan digunakan. Memiliki kelebihan yang menerima tiga Point, dan satu yang menerima Parallelogram, dapat membantu jika banyak penelepon dapat melewati hal-hal seperti itu. Namun, jika banyak Pointcontoh akhirnya dibangun tanpa tujuan selain diteruskan ke metode sekali , maka membangun objek akan membuat kode lebih lambat dan lebih sulit untuk dibaca. Jika suatu bahasa mendukung agregat yang akan dan berperilaku sebagai sekelompok nilai yang menempel bersama lakban, dan seseorang dapat melewati parameter tipe agregat hanya dengan ...
supercat

... melampirkan nilai dalam kurung kurawal, maka itu bisa bagus dari sudut pandang kinerja dan keterbacaan. Java tidak memiliki konsep seperti itu; bahasa berbasis JVM dapat mendukung hal seperti itu secara efisien untuk parameter (parameter Point p1dapat diterjemahkan ke dalam int p1_x, int p1_y), tetapi JVM tidak memiliki mekanisme yang efisien untuk fungsi untuk mengembalikan hal seperti itu.
supercat

12

Entah mengomentari semuanya atau berkomentar apa-apa (jelas mengomentari semuanya adalah pilihan yang jauh lebih baik). Pikirkan tentang seseorang yang menggunakan kode Anda, baik meninjau API Anda langsung di file sumber Anda atau dalam file doc yang dihasilkan (yaitu keluaran doxygen). Ketidakkonsistenan pada umumnya menyebabkan kebingungan, yang mengarah pada waktu yang dihabiskan untuk menggali sumber untuk mencari tahu mengapa sesuatu tidak dikomentari, yang mengarah pada waktu yang terbuang yang bisa dihindari seandainya parameter baru saja dikomentari di tempat pertama.

Ingat: Sesuatu yang masuk akal bagi Anda dapat diartikan sepenuhnya berbeda oleh orang lain, tidak peduli seberapa biasa Anda memikirkannya (pikirkan tentang seseorang yang tidak sekuat bahasa Inggris dalam membaca dan mencoba memahami kode Anda).

Setelah mengatakan semua itu, jika pengembang lain menekankan pentingnya mendokumentasikan semuanya, maka sama pentingnya (jika tidak lebih) perlu dilakukan untuk menjaga agar dokumentasi tetap mutakhir. Seperti yang Anda nyatakan, tidak ada yang lebih buruk daripada memiliki komentar yang ketinggalan zaman (sama buruknya, jika tidak lebih buruk dari dokumen yang dihilangkan).


10

Mari kita mulai dari asumsi bahwa siklus pengembang adalah sumber daya yang kita coba untuk pelihara.

Jadi itu berarti bahwa pengembang seharusnya tidak membuang waktu untuk mendokumentasikan parameter yang jelas dan mengembalikan nilai, kan?

Baiklah, mari kita jabarkan.

Jika kita mendokumentasikan semuanya, menganggap komentar marjinal benar-benar sepele dan tidak memerlukan pemikiran atau penelitian, biaya adalah waktu tambahan untuk benar-benar mengetik komentar dan memperbaiki kesalahan ketik.

Jika kita memilih, maka biayanya adalah:

  • Memiliki dan memenangkan argumen dengan pengembang lain di tim Anda yang berpikir semuanya harus didokumentasikan.
  • Untuk setiap parameter, tentukan apakah ini harus atau tidak harus didokumentasikan.
  • Lebih banyak argumen dengan tim Anda ketika seseorang memiliki pendapat berbeda tentang apakah suatu parameter seharusnya didokumentasikan.
  • Menghabiskan waktu memburu kode dan meneliti ketika parameter yang dianggap cukup jelas ternyata tidak begitu.

Jadi, saya cenderung hanya mendokumentasikan semuanya. Kelemahan pasti, tetapi terkandung.


9

Jika Anda tetap menulis Javadoc, Anda sebaiknya menuliskannya sepenuhnya, bahkan termasuk parameter "jelas". Mereka mungkin jelas bagi Anda atau pengembang lain, tetapi siapa pun yang baru melihatnya akan mendapat manfaat dari mengetahui maksud dari setiap parameter.

Adapun untuk menjaga Javadoc dengan benar, Anda perlu menggunakan alat untuk pengembangan Anda yang membantu Anda dengan ini. Eclipse muncul di pikiran. Tentu saja, jika ini penting, Anda harus memastikan bahwa semua orang di tim melakukan bagian mereka untuk menjaga kode, termasuk komentar.


3

Jangan lupa bahwa javadoc dapat dibuat terlihat sementara terpisah dari kode, contoh utama adalah Java API itu sendiri. Dengan tidak memasukkan javadoc untuk setiap parameter dalam suatu metode, Anda salah mengartikan metode tersebut dan bagaimana cara menggunakannya.


Apakah "a - argumen yang nilai absolutnya ditentukan" benar-benar menambah sesuatu pada dokumentasi Math.abs?
kevin cline

@Kevin cline bisa berguna untuk orang yang sulit berpikir ;-)
Gary Rowe

1

'perlu' sepenuhnya subjektif. Saya pikir yang Anda tanyakan adalah, 'dalam situasi Anda, sebaiknya Anda menambahkan komentar javadoc'. Tidak mengetahui ruang lingkup atau konteks aplikasi Anda, bagaimana kami tahu apa yang sesuai untuk Anda?

Jika kode yang terbuka untuk umum ini (yaitu, kode yang dimaksudkan untuk diakses orang lain, seperti api) maka ya, dokumentasikan setiap parameter tunggal. Jangan menganggap pembaca tahu tentang proyek sebanyak yang Anda lakukan. Tetapi sebaliknya, terserah Anda dan tim Anda untuk membuat keputusan sendiri.


6
Saya menemukan bahwa walaupun itu tidak menghadap publik, ini membantu saya untuk memahami kode saya sendiri ketika saya melihatnya kembali bertahun-tahun kemudian: P
Demian Brecht

1
Pendekatan ini juga dikenal sebagai "Heck kita akan membuat orang baru harus membaca kode sialan dalam 4 tahun setelah kita pergi." pendekatan.
Tim Williscroft
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.