Kode yang didokumentasikan sendiri vs Javadocs?

Baru-baru ini saya telah mengerjakan refactoring bagian-bagian dari basis kode yang saat ini saya tangani - tidak hanya untuk memahaminya dengan lebih baik, tetapi juga untuk membuatnya lebih mudah bagi orang lain yang mengerjakan kode.

Saya cenderung bersandar pada sisi berpikir bahwa mendokumentasikan kode sendiri itu bagus . Saya hanya berpikir itu lebih bersih dan jika kode berbicara sendiri, yah ... Itu bagus .

Di sisi lain kami memiliki dokumentasi seperti javadocs. Saya juga suka ini, tetapi ada risiko tertentu bahwa komentar di sini sudah ketinggalan zaman (dan tentu saja komentar pada umumnya). Namun, jika mereka up-to-date, mereka bisa sangat berguna mengatakan, memahami algoritma yang kompleks.

Apa praktik terbaik untuk ini? Di mana Anda menggambar garis antara kode yang mendokumentasikan diri dan javadocs?

Kode dokumentasi diri (dan komentar dalam kode) dan komentar Javadoc memiliki dua audiens target yang sangat berbeda.

Kode dan komentar yang tersisa di file kode adalah untuk pengembang. Anda ingin mengatasi masalah mereka di sini - membuatnya mudah untuk memahami apa kode itu dan mengapa kode itu seperti itu. Penggunaan nama variabel yang sesuai, metode, kelas, dan sebagainya (kode dokumentasi diri) ditambah dengan komentar mencapai ini.

Komentar Javadoc biasanya untuk pengguna API. Ini juga pengembang, tetapi mereka tidak peduli dengan struktur internal sistem, hanya kelas, metode, input, dan output sistem. Kode tersebut terkandung dalam kotak hitam. Komentar-komentar ini harus digunakan untuk menjelaskan bagaimana melakukan tugas-tugas tertentu, apa hasil operasi yang diharapkan, ketika pengecualian dilemparkan, dan apa nilai input artinya. Dengan serangkaian dokumentasi yang dibuat oleh Javadoc, saya seharusnya dapat sepenuhnya memahami cara menggunakan antarmuka Anda tanpa pernah melihat satu pun baris kode Anda.

Kode mengatakan bagaimana . Komentar mengatakan mengapa , dan mungkin bahkan mengapa tidak .

Adalah tugas Anda untuk menyediakan bagi pembaca dan pengelola kode Anda di masa mendatang. Masukkan semua yang Anda bisa dalam kode, dan sisanya di komentar.

Perhatikan bahwa hal-hal yang paling sulit ditangkap adalah keputusan desain - ingat juga itu.

Menggunakan Javadocs tidak membuat perbedaan nyata - karena dokumen yang dihasilkan berisi nama fungsi Anda bersama dengan teks dari komentar, sama sekali tidak ada alasan mengapa Anda harus mengulangi apa pun di komentar yang jelas dari nama fungsi itu sendiri.

Jika, di sisi lain, Anda memiliki fungsi di mana seseorang harus melihat implementasi terlebih dahulu untuk memahami apa yang baik untuk (sehingga tidak membuat informasi ini tersedia untuk Javadocs), maka kode tersebut adalah IMHO tidak mendokumentasikan sendiri, tidak peduli seberapa jelas implementasinya.

Saya pikir dengan javadocs, semuanya sama dengan dokumentasi apa pun - aturan utamanya adalah:

ikuti audiensi

Apakah banyak orang membaca javadocs Anda? Jika ya, masuk akal untuk menginvestasikan upaya untuk memperbaikinya.

Apakah pembaca Anda cenderung tidak membaca kode demi mempelajari javadocs? Jika ya, masuk akal dua kali lebih banyak untuk menghabiskan upaya menulisnya dengan baik.

• Ini persis dengan dokumentasi JDK . Tebak Sun / Oracle menghabiskan banyak upaya untuk hal ini dan mereka tampaknya memiliki pengembalian yang bagus dalam dokumen API yang banyak digunakan oleh komunitas.

Sekarang, apakah ini kasus Anda? Jika tidak, pikirkan dua kali apakah upaya yang diinvestasikan ke javadocs dibenarkan.

Seperti yang sudah ditunjukkan di atas, dengarkan audiens untuk mencari tahu jalannya.

• Jika Anda mendengar keluhan aktif tentang dokumentasi yang tidak mencukupi, pertimbangkan untuk berinvestasi untuk memperbaikinya.
   
  Jika, di sisi lain, yang Anda dengar adalah pengembang yang mengeluh tentang aturan braindead yang memaksa mereka membuang waktu untuk mengetik yang tidak berguna, maka kemungkinan besar upaya javadocs Anda seperti berinvestasi dalam hipotek subprime . Pikirkan investasi yang lebih baik sebagai gantinya.

Saya hanya ingin mengomentari kekhawatiran bahwa komentar Javadoc mungkin sudah usang. Meskipun @JonathanMerlet benar dalam mengatakan bahwa Javadoc harus stabil, Anda juga dapat membantu dengan meninjau Javadoc dan komentar serta kode selama peer review. Apakah komentar sesuai dengan apa yang dilakukan kode? Jika tidak, yang salah, dan bersikeras pengembang memperbaikinya. Cobalah mendorong pengembang lain untuk melakukan hal yang sama. Ini membantu tidak hanya memperbarui dokumentasi eksternal (komentar Javadoc), tetapi juga komentar kode biasa. Ini membantu pengembang yang datang setelah refactoring Anda memahami kode lebih cepat dan mudah, dan membuatnya lebih sederhana di masa mendatang.

Saya pikir javadocs sesuai untuk bagian-bagian yang harus tetap stabil (API) sehingga risiko komentar yang keluar dari tanggal diminimalkan, sedangkan kode dokumentasi diri sangat bagus untuk apa yang sering mengalami perubahan (implementasi). Tentu saja, API dapat berubah selama proyek berlangsung, tetapi memiliki tajuk tepat sebelum deklarasi, menjaga keduanya agar tetap sinkron tidak sulit (dibandingkan dengan komentar pada beberapa baris yang menjelaskan beberapa baris kode)