Apakah komentar dianggap sebagai bentuk dokumentasi?

Ketika saya menulis skrip kecil untuk diri saya sendiri, saya menumpuk kode saya tinggi dengan komentar (kadang-kadang saya berkomentar lebih dari saya kode). Banyak orang yang saya ajak bicara mengatakan bahwa saya harus mendokumentasikan skrip-skrip ini, meskipun bersifat pribadi, sehingga jika saya pernah menjualnya, saya akan siap. Tetapi bukankah komentar merupakan bentuk dokumentasi?

Bukankah ini:

$foo = "bar"; # this is a comment
print $foo; # this prints "bar"

dianggap dokumentasi, terutama jika pengembang menggunakan kode saya? Atau apakah dokumentasi dianggap berada di luar kode itu sendiri?

Komentar pasti dokumentasi. Untuk sebagian besar proyek, komentar (sayangnya) merupakan bentuk utama dokumentasi proyek. Untuk alasan ini, sangat penting untuk memperbaikinya. Anda perlu memastikan bahwa dokumentasi ini tetap akurat meskipun ada perubahan kode. Ini adalah masalah umum dengan komentar. Pengembang sering "menghilangkan" mereka ketika mereka bekerja dengan kode yang sudah dikenal, sehingga mereka lupa untuk memperbarui komentar untuk mencerminkan kode. Ini dapat membuat komentar yang kedaluwarsa dan menyesatkan.

Banyak orang menyarankan untuk membuat kode sendiri. Ini berarti bahwa alih-alih komentar, Anda merestrukturisasi kode Anda untuk menghapus kebutuhan mereka. Ini dapat menghilangkan sebagian besar komentar "apa" dan "bagaimana", tetapi tidak benar-benar membantu dengan komentar "mengapa". Meskipun ini mungkin bekerja secara efektif untuk menghilangkan sebagian besar komentar, masih ada banyak waktu di mana menulis komentar adalah cara paling sederhana dan paling efisien untuk mendokumentasikan sepotong kode.

Mereka adalah bentuk dokumentasi, tetapi ingat bahwa dokumentasi ada di mata yang melihatnya ....

• Bagi sebagian orang, kode dokumentasi diri sudah cukup. Tapi itu mengasumsikan tingkat detail teknis sebagai pelanggan. Kita harus hati-hati berpikir bahwa ini sudah cukup, karena ego kita dapat mengatakan kepada kita "Jelas apa yang dilakukan kode ini" tetapi waktu dapat membuktikan sebaliknya. Ini juga mengasumsikan Anda tahu terlebih dahulu keterampilan pembaca.

• Bagi mereka yang melihat kode sumber tetapi dengan keahlian teknis yang kurang, komentar bisa saja ok. Tapi itu mengasumsikan seseorang melihat kode sumbernya.

• Jika Anda teknis, tetapi kurang waktu untuk membaca semua kode sumber, manual teknis bisa menjadi apa yang diperlukan.

• Jika pengguna tidak memiliki keterampilan teknis, tetapi hanya perlu tahu apa yang terjadi, dokumentasi pengguna adalah yang diperlukan.

Jadi pertanyaan sebenarnya adalah siapa pelanggan Anda? Jika ya, maka kode atau komentar yang mendokumentasikan diri sendiri sudah cukup. Jika itu untuk orang lain, Anda mungkin ingin memperluas cara Anda mendokumentasikan.

Ya, komentar adalah bentuk dokumentasi. Apakah itu dokumentasi yang berguna atau tidak bagi seseorang yang harus memelihara atau memperbarui kode Anda adalah pertanyaan terbuka.

Saya tahu Anda bermaksud sebagai contoh sekali pakai, tetapi hal-hal seperti

print $foo; # this prints "bar"

tidak berguna; itu hanya menambah kekacauan visual. Jangan mendokumentasikan yang sudah jelas.

Memblokir komentar di bagian atas definisi metode atau fungsi yang menggambarkan fungsi atau tujuan metode (dalam istilah tingkat tinggi ), input, output, nilai pengembalian (jika ada), pengecualian (jika ada), prasyarat, dan kondisi akhir berguna, tetapi hanya sampai pada taraf mereka memberi tahu seseorang bagaimana fungsi atau metode itu seharusnya digunakan. Mereka tidak menjelaskan mengapa fungsi itu ada.

Jika orang lain perlu mempertahankan kode Anda, maka Anda perlu mendokumentasikan persyaratan dan desain di suatu tempat, dan itu biasanya tidak dilakukan dalam kode sumber itu sendiri.

Saya mendapati pendekatan Bob Martin terhadap hal ini, dari Clean Code, biasanya menyelesaikan masalah apakah Anda merasa Anda terlalu banyak berkomentar atau kurang berkomentar dan meninggalkan dokumentasi:

Kami adalah penulis. Dan satu hal tentang penulis adalah mereka memiliki pembaca. Memang, penulis bertanggung jawab untuk berkomunikasi dengan baik dengan pembaca mereka. Lain kali Anda menulis sebaris kode, ingat Anda adalah seorang penulis, menulis untuk pembaca yang akan menilai upaya Anda.

... rasio waktu yang dihabiskan membaca dan menulis lebih dari 10: 1. Kami terus membaca kode lama sebagai bagian dari upaya untuk menulis kode baru.

Jadi dengan kata lain, apakah kode Anda cukup jelas tanpa dokumentasi? Tidak ada aturan yang ditetapkan untuk itu (kecuali jika Anda bekerja untuk orang seperti Microsoft yang dokumentasinya dapat diakses publik), sebagian besar adalah untuk membantu pembaca kode di masa mendatang yang sering kali adalah Anda.

Dokumentasi harus mendokumentasikan Mengapa bukan Bagaimana . The Bagaimana harus jelas dalam kode, yaitu kecuali itu adalah beberapa trik optimasi misterius atau teknik bahasa tertentu lainnya yang tidak umum yang terjadi.

The Mengapa mungkin tidak harus dalam kode, harus berada di tempat lain seperti jaminan produk, yang terikat untuk melakukan komentar dengan id cerita yang dapat dicari dalam log perubahan atau nama cabang.

Komentar adalah bentuk dokumentasi. Bentuk yang lebih rendah, dan yang menunjukkan Anda telah menemukan area kode Anda yang dapat difaktorkan dengan lebih baik.

Sepertinya Anda berkomentar secara kompulsif. Memiliki pilihan lain mungkin merupakan hal yang baik. Saya dapat memikirkan tiga bentuk dokumentasi unggul:

1) Faktorkan kode Anda lebih baik. Alih-alih menambahkan komentar, ekstrak metode atau fungsi yang namanya adalah teks dari komentar yang akan Anda tulis. Jadi kodenya mengatakan apa yang akan dikatakan komentar Anda.

2) Tes. Ini adalah bentuk dokumentasi yang biasanya saya cari. Tes unit dan tes penerimaan adalah dokumentasi langsung, dan dapat dibaca dengan mudah jika banyak metode bermakna digunakan untuk menyatakan maksud, seperti pada poin 1.

3) Untuk skrip, opsi --help. Di sinilah Anda bisa menjadi gila pada doc. Tetap pada contoh, mengantisipasi apa yang dibutuhkan pengguna.

Singkatnya, jika Anda cenderung untuk tetap memberikan komentar, periksa apakah ada cara untuk berkomunikasi dengan pembaca dengan menyusun kode dengan lebih baik. Atau ada tes yang mengomunikasikan mengapa kode itu ada? Jika Anda masih merasa ingin berkomentar, akui kekalahan, dan lakukan.