Mendokumentasikan basis kode warisan
Saya sangat merekomendasikan mengikuti aturan scout dengan basis kode lama. Mencoba mendokumentasikan proyek warisan secara mandiri tanpa mengerjakannya tidak akan pernah terjadi.
Dokumentasi dalam kode
Yang paling penting adalah menggunakan fasilitas dokumentasi di lingkungan pengembangan yang Anda pilih, sehingga itu berarti pydoc untuk python, javadoc di java atau komentar xml dalam C #. Ini memudahkan untuk menulis dokumentasi pada saat yang sama dengan menulis kode.
Jika Anda mengandalkan untuk kembali dan mendokumentasikan sesuatu nanti, Anda mungkin tidak menyiasati hal itu, tetapi jika Anda melakukannya saat Anda menulis kode, maka apa yang perlu didokumentasikan akan menjadi segar dalam pikiran Anda. C # bahkan memiliki opsi untuk mengeluarkan peringatan kompilasi jika dokumentasi XML tidak lengkap atau tidak konsisten dengan kode aktual.
Tes sebagai dokumentasi
Aspek penting lainnya adalah memiliki integrasi yang baik dan pengujian unit.
Seringkali dokumentasi berkonsentrasi pada apa yang dilakukan kelas dan metode secara terpisah, melompati cara mereka digunakan bersama untuk menyelesaikan masalah Anda. Tes sering menempatkan ini ke dalam konteks dengan menunjukkan bagaimana mereka berinteraksi satu sama lain.
Demikian pula, tes unit sering menunjukkan ketergantungan eksternal secara eksplisit melalui mana hal-hal yang perlu diejek .
Saya juga menemukan bahwa menggunakan pengembangan yang digerakkan oleh Test, saya menulis perangkat lunak yang lebih mudah digunakan, karena saya menggunakannya langsung dari kata go. Dengan kerangka pengujian yang baik, membuat kode lebih mudah untuk diuji dan membuatnya mudah digunakan seringkali merupakan hal yang sama.
Dokumentasi tingkat tinggi
Akhirnya ada apa yang harus dilakukan tentang tingkat sistem dan dokumentasi arsitektur. Banyak yang menganjurkan menulis dokumentasi seperti itu di wiki atau menggunakan Word atau pengolah kata lain, tetapi bagi saya tempat terbaik untuk dokumentasi tersebut juga di samping kode, dalam format teks biasa yang ramah sistem kontrol versi.
Sama seperti dengan dokumentasi dalam-kode, jika Anda menyimpan dokumentasi tingkat yang lebih tinggi dalam repositori kode Anda, maka Anda akan cenderung memperbaruinya. Anda juga mendapatkan manfaat bahwa ketika Anda mengeluarkan versi XY kode, Anda juga mendapatkan versi XY dokumentasi. Selain itu, jika Anda menggunakan format ramah VCS, maka itu berarti mudah untuk bercabang, berbeda, dan digabungkan, seperti halnya kode Anda.
Saya sangat suka pertama , karena mudah untuk menghasilkan halaman html dan dokumen pdf dari itu, dan jauh lebih ramah daripada LaTeX , namun masih dapat menyertakan ekspresi matematika LaTeX saat Anda membutuhkannya.