Bagaimana cara mendokumentasikan kode?
Anda sudah memiliki petunjuk: lihat bagaimana Java API didokumentasikan.
Secara umum, tidak ada seperangkat aturan unik yang berlaku untuk setiap proyek. Ketika saya bekerja pada proyek skala besar yang kritis terhadap bisnis, dokumentasi tidak ada hubungannya dengan yang saya akan tulis untuk perpustakaan sumber terbuka kecil, yang, pada gilirannya, tidak ada hubungannya dengan dokumentasi proyek pribadi skala menengah saya .
Mengapa banyak proyek open source tidak terdokumentasi dengan baik?
Karena sebagian besar proyek open source dibuat oleh orang-orang yang berkontribusi pada proyek-proyek itu karena itu menyenangkan. Sebagian besar programmer dan pengembang menganggap bahwa menulis dokumentasi tidak cukup menyenangkan untuk dilakukan secara gratis.
Mengapa banyak proyek sumber tertutup tidak terdokumentasi dengan baik?
Karena memerlukan biaya yang sangat besar untuk (1) menulis dokumentasi yang baik dan (2) memeliharanya.
Biaya langsung (biaya penulisan dokumentasi) jelas terlihat oleh para pemangku kepentingan: jika tim Anda meminta untuk menghabiskan dua bulan ke depan untuk mendokumentasikan proyek, itu adalah dua bulan tambahan gaji untuk dibayar.
Biaya jangka panjang (biaya pemeliharaan dokumentasi) menjadi mudah terlihat bagi para manajer, dan seringkali menjadi target pertama ketika mereka harus menurunkan biaya atau memperpendek penundaan. Hal ini menyebabkan masalah tambahan pada dokumentasi usang yang dengan cepat menjadi tidak berguna, dan sangat mahal untuk diperbarui.
Penghematan jangka panjang (penghematan karena tidak perlu membuang waktu beberapa hari menjelajahi kode warisan hanya untuk memahami hal-hal dasar yang seharusnya telah didokumentasikan bertahun-tahun yang lalu), di sisi lain, sulit untuk diukur, yang menegaskan perasaan beberapa manajer bahwa menulis dan memelihara dokumentasi adalah buang-buang waktu.
Yang sering saya amati adalah:
Pada awalnya, tim bersedia banyak mendokumentasikan.
Seiring waktu, tekanan tenggat waktu dan kurangnya minat membuatnya semakin sulit untuk mempertahankan dokumentasi.
Beberapa bulan kemudian, orang baru yang bergabung dengan proyek secara praktis tidak dapat menggunakan dokumentasi, karena tidak sesuai sama sekali dengan sistem yang sebenarnya.
Memperhatikan hal itu, manajemen menyalahkan pengembang karena tidak memelihara dokumentasi; pengembang meminta untuk menghabiskan beberapa minggu memperbaruinya.
Jika manajemen memberikan beberapa minggu untuk itu, siklus berulang.
Jika manajemen menolak, berdasarkan pengalaman sebelumnya, itu hanya menambah pengalaman buruk, karena produk tidak memiliki dokumentasi, tetapi beberapa bulan dihabiskan untuk menulis dan memeliharanya.
Dokumentasi harus merupakan proses yang berkelanjutan, seperti halnya pengujian. Menghabiskan satu minggu hanya dengan mengkode beberapa ribu LOC, dan kembali ke tes dan dokumentasi sangat, sangat menyakitkan.
Bagaimana mendorong tim untuk menulis dokumentasi?
Demikian pula dengan cara mendorong orang untuk menulis kode bersih, melakukan refactoring secara teratur, menggunakan pola desain atau menambahkan tes unit yang cukup.
Menurut contoh. Jika Anda menulis dokumentasi yang baik, pasangan Anda mungkin mulai melakukannya juga.
Lakukan tinjauan kode sistematis, termasuk tinjauan kode formal yang ditargetkan untuk memeriksa dokumentasi.
Jika beberapa anggota tim sangat antipati terhadap dokumentasi yang baik (atau dokumentasi sama sekali), diskusikan subjek tersebut dengan mereka secara pribadi, untuk memahami hambatan apa yang menghalangi mereka untuk menulis dokumentasi yang lebih baik. Jika mereka menyalahkan kurangnya waktu, Anda melihat sumber masalahnya.
Jadikan kehadiran atau kurangnya dokumentasi dapat diukur selama beberapa minggu atau bulan, tetapi jangan fokus pada hal itu. Misalnya, Anda dapat mengukur jumlah baris komentar per LOC, tetapi jangan menjadikannya sebagai ukuran permanen, jika tidak, pengembang akan mulai menulis komentar yang panjang tetapi tidak berarti hanya untuk menghilangkan skor rendah.
Gunakan gamification. Ini datang bersamaan dengan poin sebelumnya.
Gunakan penguatan positif / negatif .
(Lihat komentar oleh SJuan76 ) Perlakukan kurangnya komentar sebagai kesalahan. Misalnya, di Visual Studio, Anda dapat memeriksa opsi untuk menghasilkan dokumentasi XML. Jika Anda juga memeriksa bahwa semua peringatan diperlakukan sebagai kesalahan, kurangnya komentar di bagian atas kelas atau metode akan menghentikan kompilasi.
Adapun tiga poin sebelumnya, yang ini harus digunakan dengan hati-hati. Saya menggunakannya untuk sementara waktu dengan tim programmer pemula yang tangguh, dan berakhir dengan komentar yang sesuai dengan StyleCop seperti itu:
/// <summary>
/// Gets or sets the PrimaryHandling.
/// </summary>
public Workflow PrimaryHandling { get; set; }
yang, hm ..., tidak terlalu membantu.
Ingat: tidak ada yang otomatis yang dapat membantu Anda menentukan komentar buruk ketika programmer ingin mengacaukan Anda . Hanya ulasan kode dan tugas manusia lainnya yang akan membantu.
Apakah ada contoh yang baik ketika dokumentasi minimal atau tidak diperlukan?
Dokumentasi yang menjelaskan arsitektur dan desain tidak diperlukan:
Untuk prototipe,
Untuk proyek pribadi yang ditulis dalam beberapa jam untuk menyelesaikan tugas, sambil cukup yakin proyek ini tidak akan dipertahankan lagi,
Untuk proyek mana pun yang jelas, mengingat ukurannya yang kecil, ditambah dengan kode yang sangat bersih, Anda akan menghabiskan lebih banyak waktu menulis dokumentasi daripada semua pengelola masa depan yang mengeksplorasi kode tersebut.
Dokumentasi dalam kode (komentar kode) tidak diperlukan menurut beberapa pengembang ketika kode itu mendokumentasikan diri. Bagi mereka, kehadiran komentar adalah, kecuali dalam kasus yang jarang terjadi, bukan pertanda baik, tetapi pertanda bahwa kode tidak cukup di refactored untuk menjadi jelas tanpa perlu komentar.
Saya merasa bahwa kita harus memiliki tinjauan dokumentasi setelah sebuah proyek dikirimkan.
Jika proyek Anda dikirimkan setidaknya sekali seminggu, itu cara yang tepat. Jika proyek Anda tidak gesit dan dikirim dengan interval enam bulan, maka lakukan tinjauan yang lebih teratur.