Bagaimana cara melakukan dokumentasi untuk kode dan mengapa perangkat lunak (sering) kurang didokumentasikan?

Ada beberapa contoh kode yang didokumentasikan dengan baik di luar sana, seperti java api. Tetapi, banyak kode dalam proyek publik seperti git dan proyek internal perusahaan tidak terdokumentasi dengan baik dan tidak terlalu ramah bagi pendatang baru.

Dalam semua tugas pengembangan perangkat lunak saya, saya harus berurusan dengan kode yang tidak terdokumentasi dengan baik. Saya perhatikan hal-hal berikut -

1. Sedikit atau tidak ada komentar dalam kode.
2. Nama metode dan variabel tidak menggambarkan diri.
3. Ada sedikit atau tidak ada dokumentasi untuk bagaimana kode cocok dengan sistem atau proses bisnis.
4. Mempekerjakan pengembang yang buruk atau tidak membimbing yang baik. Mereka tidak dapat menulis kode sederhana dan bersih. Karenanya sulit atau tidak mungkin bagi siapa pun, termasuk pengembang untuk mendokumentasikan kode.

Sebagai hasilnya, saya harus melalui banyak kode dan berbicara dengan banyak orang untuk mempelajari banyak hal. Saya merasa ini menghabiskan waktu semua orang. Ini juga menciptakan kebutuhan untuk KT / sesi transfer Pengetahuan untuk pendatang baru ke proyek.

Saya belajar bahwa dokumentasi tidak mendapat perhatian yang layak karena alasan berikut:

1. Kemalasan.
2. Pengembang tidak suka melakukan apa pun selain kode.
3. Keamanan kerja. (Jika tidak ada yang bisa memahami kode Anda dengan mudah, maka Anda mungkin tidak mudah diganti.)
4. Tenggat waktu yang sulit menyisakan sedikit waktu untuk mendokumentasikan.

Jadi, saya bertanya-tanya apakah ada cara untuk mendorong dan menegakkan praktik dokumentasi yang baik di perusahaan atau proyek. Apa strategi yang digunakan untuk membuat dokumentasi yang layak untuk sistem dan kode proyek apa pun, terlepas dari kerumitannya? Apakah ada contoh yang baik ketika dokumentasi minimal atau tidak diperlukan?

IMHO, saya merasa bahwa kita harus memiliki tinjauan dokumentasi setelah sebuah proyek dikirimkan. Jika tidak sederhana, ringkas, ilustratif, dan ramah pengguna, pengembang atau teknisi dokumentasi teknis memikul tanggung jawab untuk itu dan dibuat untuk memperbaikinya. Saya juga tidak berharap orang membuat rim dokumentasi, tidak berharap bahwa itu akan ramah pengguna seperti buku-buku kepala pertama, tapi saya berharap itu untuk menghilangkan kebutuhan akan jam analisis dan sesi KT yang sia-sia.

Apakah ada cara untuk mengakhiri atau mengurangi kegilaan ini? "Pengembangan berbasis dokumen" mungkin?

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.

1. 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.

2. 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.

3. 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:

1. Pada awalnya, tim bersedia banyak mendokumentasikan.

2. Seiring waktu, tekanan tenggat waktu dan kurangnya minat membuatnya semakin sulit untuk mempertahankan dokumentasi.

3. Beberapa bulan kemudian, orang baru yang bergabung dengan proyek secara praktis tidak dapat menggunakan dokumentasi, karena tidak sesuai sama sekali dengan sistem yang sebenarnya.

4. 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.

Saya pikir Anda harus membuat perbedaan antara komentar dan dokumentasi. Walaupun komentar bersifat deskriptif, tidak konsisten, namun tersebar di seluruh kode. Komentar tidak boleh mengkompensasi kode yang tidak cukup menggambarkan diri sendiri, sebaliknya harus mengisyaratkan programmer lain pada bagian yang sulit.

Apakah kode harus didokumentasikan tergantung pada skala proyek. Tentunya ada orang yang percaya bahwa semuanya harus didokumentasikan, dan tampaknya mudah untuk membenarkan pemikiran itu karena siapa yang berani menentang mendokumentasikan pengetahuan? Untungnya pengembangan perangkat lunak bukan ilmu pengetahuan, dan dunia tidak runtuh jika detail di balik program kecil Anda menjadi tidak jelas. Sekarang mengenai perangkat lunak profesional untuk digunakan oleh banyak pengembang, ya jelas Anda harus mendokumentasikan kode Anda. Tetapi jika Anda berada dalam posisi untuk kode pada tingkat itu, maka Anda jelas akan tahu itu.

tl; dr

Jika Anda meminta setiap proyek untuk didokumentasikan dengan baik, maka Anda terlalu banyak bertanya.