Apa yang harus saya sertakan dalam tajuk dokumentasi kelas saya

Saya mencari format dokumentasi kelas informatif untuk kelas Entitas, Logika Bisnis, dan Akses Data saya.

Saya menemukan dua format berikut dari sini

Format 1

///-----------------------------------------------------------------
///   Namespace:      <Class Namespace>
///   Class:          <Class Name>
///   Description:    <Description>
///   Author:         <Author>                    Date: <DateTime>
///   Notes:          <Notes>
///   Revision History:
///   Name:           Date:        Description:
///-----------------------------------------------------------------

Format 2

// ===============================
// AUTHOR     :
// CREATE DATE     :
// PURPOSE     :
// SPECIAL NOTES:
// ===============================
// Change History:
//
//==================================

Saya merasa mengikuti adalah elemen dasar

• Penulis
• Tanggal dibuat
• Deskripsi
• Riwayat Revisi

sebagai Namespace dan nama Kelas akan tetap ada di sana.

Tolong beri tahu saya pendapat Anda, format mana yang disarankan dan apakah ada cara standar penulisan riwayat revisi?

Sebagian besar informasi yang Anda sarankan di sana akan ditemukan di repositori sumber.

Satu-satunya hal yang benar-benar Anda butuhkan adalah bagian tujuan, yang mengatakan untuk apa kelas itu ada.

Apakah membosankan untuk mencari di repositori setiap kali Anda ingin mengetahui informasi lainnya? Saya akan mengatakan tidak. Seberapa sering Anda peduli siapa penulis aslinya? Atau kapan file pertama kali dibuat? Plugin (seperti Ankh SVN untuk Visual Studio) sering memungkinkan Anda untuk mengklik kanan dalam file Anda saat ini dan melihat log repoistory untuk file tersebut, sehingga tidak terlalu merepotkan untuk benar-benar melihat informasi ini.

Selain itu, jika Anda menyimpan riwayat versi dalam komentar, komentar ini perlu dipertahankan. Jadi seiring waktu ada kemungkinan itu bisa berbohong kepada Anda. Repositori kode sumber secara otomatis menyimpan data historis ini, jadi tidak perlu pemeliharaan itu, dan akan akurat.

Memiliki kelas deskriptif, metode, dan nama variabel . Ini akan menghilangkan kebutuhan akan komentar seperti tujuan dan deskripsi. Terkadang kita berpikir bahwa semakin pendek nama metode semakin baik. Sebaliknya, buat nama metode selama yang Anda inginkan asalkan dengan jelas menggambarkan tujuannya. Hanya memiliki catatan yang sangat vital dan membantu pemahaman kode dalam beberapa cara tertentu. Saat membuat perubahan pada kode, pemrogram sering lupa untuk memperbarui komentar. Anda dapat berakhir dengan komentar dan kode tidak sinkron dan melakukan lebih banyak ruginya daripada kebaikan.

Baca artikel ini oleh Jeff Atwood - Pengodean Tanpa Komentar .

Saya menggunakan tag standar untuk menghasilkan dokumentasi. Tidak lebih, tidak kurang. Lihat disini

Saya tidak pernah memasukkan informasi yang bukan milik kelas. Penulis, data, revisi adalah data yang akan disimpan pada Sistem Kontrol Versi.

Dua format yang disajikan tidak berguna untuk menghasilkan dokumentasi dan memiliki kesalahan terbesar pada komentar, mereka mencantumkan riwayat revisi.

Banyak dari informasi ini dapat ditambahkan oleh repositori kontrol sumber Anda, membuat Anda benar-benar hanya dengan deskripsi, yang harus secara akurat menggambarkan ruang lingkup dan perilaku kelas. Saya akan merekomendasikan untuk melihat beberapa Javadoc untuk Java JDK sebagai contoh.

Segala sesuatu dalam daftar itu tidak perlu. Kontrol sumber Anda harus menangani hampir semua hal, dan apa yang tidak tercakup diurus dengan konvensi penamaan yang baik.

Jika saya harus membaca "Deskripsi" Anda untuk mengetahui apa yang dilakukan kelas Anda, maka (a) Anda menamainya buruk atau (b) Anda menulis kelas buruk yang terlalu banyak melakukan (SRP).

Saya telah bermain-main dengan mengubah template header saya karena, seperti yang orang lain tunjukkan, banyak informasi ini dapat ditemukan di repositori dan sejauh ini bidang-bidang besar yang ingin saya pertahankan adalah sebagai berikut:

• Deskripsi - Apa yang sedang dilakukan oleh kode.
• Catatan - Apa pun yang perlu diketahui tentang kode yang tidak mudah diperoleh dari komentar dalam kode itu sendiri.
• Referensi - Setiap referensi yang tergantung pada kode yang tidak dibuat jelas melalui penggunaan includeatau pernyataan serupa.

Satu item yang mungkin juga berguna untuk dimasukkan adalah bagian tentang Kata Kunci. Sementara Anda mungkin dapat melakukan pencarian untuk fungsi, kelas, struct, dll nama, mungkin ada beberapa kata kunci bahwa nama-nama lain dalam file tidak membuat jelas. Atau untuk kode yang lebih lama dan kurang terdokumentasi, ini mungkin merupakan langkah pertama dalam mendokumentasikan kode untuk pemeliharaan.

Sebagian besar jawaban lain yang saya baca sejauh ini mengasumsikan bahwa hanya ada satu repositori yang selalu tersedia

Karena sourcecode dapat kehilangan koneksi ke repositori (yaitu jika disalin) dokumentasi kelas saya menjadi seperti ini:

• class documentation header (= blok komentar di awal file) hanya berisi info hukum yang diperlukan (yaitu hak cipta oleh xyz di bawah lisensi gpl)
• segala sesuatu yang harus diketahui oleh pengembang yang menggunakan kelas harus masuk ke kelas-java-doc-comments (atau setara dengan .net) sehingga ide-s modern dapat menampilkan info ini sebagai tooltip info in sourcecode yang menggunakan kelas.

Anda juga dapat menambahkan nomor tiket untuk perbaikan bug atau permintaan fitur sehingga Anda mungkin memiliki petunjuk di mana / kapan / mengapa kelas dibuat (jika Anda cukup beruntung bahwa Anda masih dapat mengakses tiket setelah beberapa tahun).

Ketika beeing diminta untuk memperbaiki masalah dalam program lama-sumber lama warisan nomor tiket di mana cukup berharga bagi saya untuk memahami persyaratan asli kode.