Menulis komentar java doc untuk kasus uji unit

Menurut pendapat saya, kasus uji unit itu sendiri berfungsi sebagai dokumentasi untuk kode. Perusahaan saya ingin saya menulis komentar java doc terperinci di atas unit test unit. Apakah perlu melakukannya? Apakah Anda menulis komentar seperti itu?

unit-testing documentation

— Vinoth Kumar CM
sumber

anggap kode tes ditulis dengan baik dan dapat dibaca, nilai utama dari komentar semacam ini dalam kode pengujian adalah sebagai pernyataan niat .. Itu bisa sangat berharga bagi pengkode kode, bahkan diri Anda sendiri dalam waktu bertahun-tahun, karena memungkinkan Anda untuk menilai kode yang ditulis adalah melakukan apa yang seharusnya dilakukan, atau menguji apa yang seharusnya diuji. Kedua, Anda dapat menggunakan sistem seperti JAVADOC atau bahkan skrip sederhana untuk mengikis nama tes dan komentar dari kode untuk membuat sedikit dokumentasi cepat tentang tes apa yang Anda miliki dan apa yang mereka lakukan.

— Chuck van der Linden

Jawaban:

Apa yang saya lakukan adalah komentar JAVADOC:

kelas, yang menunjukkan kelas mana yang diuji unit (meskipun itu harus saya jelas karena praktik terbaik pada subjek itu menunjukkan bahwa nama kasus uji harus nama kelas + "Tes" atau + "TestCase"). Ini dilakukan dengan menggunakan komentar JAVADOC {@link XXXClass}
metode, yang menunjukkan metode mana yang diuji ({@link XXXClass # method1}). Kadang-kadang saya perlu memiliki beberapa metode pengujian untuk satu metode kelas untuk menguji semua jalur dengan benar. Ketika itu terjadi, saya menulis satu baris tambahan yang menyatakan jalur apa yang saya uji di dalam (tapi saya tidak pernah menyimpang dari konvensi satu baris saya)

Terlepas dari itu, tidak ada komentar lain. Untuk menarik perhatian mereka di tempat lain mungkin Anda bisa menggunakan sesuatu seperti Cobertura untuk menghasilkan grafik cakupan kode yang cantik dan membuatnya bahagia :-)

Catatan tambahan: Saya merujuk pada kasus uji unit, jika kita berbicara tentang kasus uji integrasi, maka satu atau dua baris lagi untuk menjelaskan apa yang sedang terjadi mungkin memang diperlukan ...

— Jalayn
sumber

Persyaratan dokumentasi untuk kode apa pun sepenuhnya tercakup dalam jawaban atas pertanyaan ini: Bos saya menginginkan penjelasan bahasa Inggris baris-demi-baris yang dikisahkan dari kode kami

Sebagai ringkasan jawaban yang akan Anda lihat di sana, "Itu tergantung pada situasi Anda". Ada kasus di mana itu masuk akal (dan didorong), dan lain-lain di mana itu adalah buang-buang waktu Anda.

— blueberryfields
sumber

Komentar Javadoc dapat diekstraksi dan diformat dalam dokumen referensi yang terpisah, unit test tidak bisa. Juga, ingatlah bahwa apa yang Anda tulis dengan kata-kata bisa berbeda dari kode yang sebenarnya, dan biasanya Anda menggambarkan dengan kata-kata perilaku yang sebenarnya diharapkan. Salah satu cara untuk menemukan bug adalah membandingkan dokumentasi dengan kode aktual, jika mereka tidak cocok - itu adalah bug (di salah satu dari mereka, dan kadang-kadang - keduanya).

Tes unit adalah untuk pengujian, bukan untuk dokumentasi. Menggunakan unit test sebagai dokumentasi salah dan tidak boleh dilakukan.

— littleadv
sumber

Saya menemukan serangkaian tes unit yang baik sangat membantu dalam mendokumentasikan kode. Mereka memberikan implementasi referensi tentang bagaimana kode seseorang harus digunakan, bersama dengan bukti bahwa kode berperilaku dengan benar ketika digunakan dengan cara itu.

— Bill Michell

@ Bill - tidak ada argumen tentang itu, ini sangat membantu. Itu tidak menggantikan dokumentasi yang tepat.

— littleadv

Tergantung pada audiens untuk dokumentasi Anda - tetapi dalam beberapa kasus Anda pasti benar.

— Bill Michell

Idealnya unit test seharusnya tidak menjadi satu-satunya dokumentasi sistem - tapi di dunia nyata, 9 proyek dari 10 bekerja dengan kode warisan di mana ia dapat dianggap beruntung memiliki setiap dokumentasi apapun. Dan dalam hal ini, saya lebih suka satu set yang baik menjalankan dan melewati unit test atas banyak dokumen yang mungkin sama sekali tidak sinkron dengan kode yang sebenarnya. (Ya, bahkan Javadoc bisa.)

— Péter Török

@ PéterTörök Ya ... Saya pindah di antara beberapa perusahaan yang berbeda, beberapa perusahaan yang sangat terkenal. Banyak kode warisan. Satu-satunya unit yang pernah diuji - yang saya tulis. Jadi, Anda sangat beruntung. Jangan berasumsi bahwa apa yang Anda lihat adalah apa yang terjadi di mana-mana. Dan bahkan jika Anda memiliki satu set unit test ... Siapa bilang itu benar? Siapa bilang mereka menutupi apa yang seharusnya? Siapa bilang hasil yang diharapkan itu apa adanya? Mengapa Anda menganggap bahwa unit test tidak tidak sinkron? Hanya karena mereka "lulus"? Omong kosong.

— littleadv