Dokumentasi kode sumber (source code)

Suatu aplikasi atau program harus memiliki dokumentasi yang baik. Membuat dokumentasi tidaklah mudah, apalagi dokumentasi pada API yang mungkin akan digunakan oleh orang lain.

Kita tidak hanya dituntut untuk mengerti bagaimana menuliskan suatu komentar didalam source code, tapi lebih dari itu kita perlu mengerti bagaimana cara mendesripsikan suatu package, class, atau method. Mendeskirpsikan yang baik berarti memberi penjelasan kepada pembaca sehingga pembaca mudah mengerti. Mendeskripsikan suatu bagian dari source code berarti memberikan penjelasan tentang karakteristik dasi suatu bagian source code tersebut. Karakteristik suatu bagian source code dapat berarti menjelaskan:

• Tujuan atau fungsi
• Algoritma spesifik yang digunakan
  
• Dependencies (Ketergantungan terhadap hal lain misalnya sistem operasi, library, dll)
  
• Karakteristik input atau output
• Informasi exception, security, deployment
• Penjelasan implementasi (misalnya pada dokumentasi Interface)
  
• Referensi ke dokumen lain
  

Dokumen Requirements for Writing Java API Specifications dianjurkan untuk dibaca karena memberikan penjelasan yang baik dan memberikan contoh-contoh dalam menuliskan dokumentasi.

Dalam perograman Java tentu kita dituntut untuk mengetahui bagaimana menggunakan tool javadoc, dan menuliskan dokumentasi pada source code yang 'javadoc friendly'. Untuk itu kita perlu baca How to Write Doc Comments for the Javadoc Tool