Menurut Anda apakah kode itu mendokumentasikan diri? [Tutup]

Ini adalah pertanyaan yang diajukan kepada saya bertahun-tahun yang lalu sebagai lulusan dalam sebuah wawancara kerja dan itu terus mengganggu otak saya sekarang dan lagi dan saya tidak pernah benar-benar menemukan jawaban bagus yang memuaskan saya.

Pewawancara yang dimaksud sedang mencari jawaban hitam dan putih, tidak ada jalan tengah. Saya tidak pernah mendapat kesempatan untuk bertanya tentang alasan di balik pertanyaan itu, tetapi saya ingin tahu mengapa pertanyaan itu diajukan kepada pengembang dan apa yang akan Anda pelajari dari jawaban ya atau tidak?

Dari sudut pandang saya sendiri, saya dapat membaca Java, Python, Delphi dll, tetapi jika manajer saya mendatangi saya dan bertanya seberapa jauh dalam sebuah proyek saya dan saya berkata "Kode sudah 80% selesai" (dan sebelum Anda mulai menembak saya, saya pernah mendengar ini diucapkan di beberapa kantor oleh pengembang), bagaimana tepatnya itu mendokumentasikan diri? Mohon maaf jika pertanyaan ini tampak aneh, tetapi saya lebih suka bertanya dan mendapatkan beberapa pendapat tentangnya untuk mendapatkan pemahaman yang lebih baik tentang mengapa pertanyaan itu diajukan kepada seseorang dalam sebuah wawancara.

Sebagian.

Kode yang menggunakan Kata-kata Bahasa Inggris Besar dapat mendokumentasikan diri sebagian karena nama-nama untuk semua fungsi dan variabel dapat memberi tahu Anda apa yang dilakukannya. Tapi itu mungkin tidak akan memberitahumu alasannya.

Membandingkan:

a->b;
# what is b doing? what is the a object?

carEngine->startIgnition;
# much more clear what objects are involved

Tetapi Anda masih tidak tahu mengapa mobil dinyalakan. Makanya, hanya sebagian. Agak mengerikan bahwa pewawancara Anda mengharapkan jawaban hitam-putih, kecuali jika pandangannya tentang hitam-putih termasuk sangat kuat.

Tidak. Kode itu sendiri tidak mendokumentasikan diri.

Alasannya adalah bahwa kode menyatakan BAGAIMANA dan tidak peduli MENGAPA itulah yang perlu diketahui manusia untuk mempertahankan kode.

Karenanya Anda perlu komentar tambahan yang menjelaskan semua MENGAPA . Anda dapat membatasi mereka dengan membiarkan nama variabel Anda memasukkan beberapa bagian dari keputusan, tetapi Anda tidak dapat menghindarinya.

Kode yang tepat memberi tahu Anda " bagaimana ". Komentar yang tepat memberi tahu Anda " mengapa " .

Oleh karena itu kode dapat mendokumentasikan diri sendiri bagaimana hal-hal dicapai, tetapi Anda tidak dapat menganggapnya mendokumentasikan alasan mengapa.

Jika mereka bersikeras untuk menjawab hitam dan putih tanpa jalan tengah, jawabannya adalah tidak.

Jawaban yang lebih lengkap adalah bahwa kode harus mendokumentasikan diri sendiri sampai batas maksimum yang masuk akal, tetapi tidak ada cara yang masuk akal untuk memasukkan beberapa jenis dokumentasi dalam kode. Contohnya saja, kode tersebut mungkin dapat digunakan untuk mendokumentasikan informasi apa yang dikumpulkan pada formulir A, apa yang ada di formulir B dan apa yang ada di formulir C. Biasanya tidak akan (dan mungkin tidak boleh) berupaya untuk mendokumentasikan tes yang menunjukkan pembagian itu. data dengan cara itu mengurangi kesalahan x% dibandingkan dengan (misalnya) hanya menggunakan dua bentuk, bukan tiga.

Apa pun kecuali bagian kode yang paling sepele bisa mendapat manfaat dari setidaknya beberapa dokumentasi luar.

Jawabanku. Sedapat mungkin, Anda harus berusaha membuat kode Anda mendokumentasikan diri sendiri sebaik mungkin. Ada banyak alasan untuk ini. Ketika awalnya ditulis, rata-rata satu baris dalam 10 memiliki kesalahan. Kesalahan dalam kode cenderung ditemukan dan diperbaiki. Kesalahan dalam dokumentasi cenderung ditinggalkan. Dan dalam pemeliharaan itu umum untuk kode dan dokumentasi terpisah.

Yang mengatakan, ada batasan untuk apa yang dapat dilakukan dengan membuat kode menjadi jelas. Dalam hal ini, Anda harus mendokumentasikan.

Bagaimana dengan kasus di mana Anda memiliki pilihan tentang dokumentasi? Pandangan saya adalah pemeliharaan sangat tergantung pada organisasi Anda. Jika Anda memiliki pengembang perangkat lunak yang sangat baik dan proses peninjauan kode yang ketat (seperti, misalnya, Google), maka proses dan orang-orang Anda dapat sedemikian rupa sehingga Anda tidak perlu khawatir tentang komentar yang gagal dipertahankan. Dalam hal ini gaya yang jauh lebih banyak komentar-berat masuk akal. (Google, pada kenyataannya, memiliki gaya komentar-berat.) Namun jika Anda memiliki organisasi yang lebih khas maka saya akan sangat tidak mempercayai komentar yang saya lihat, dan saya akan berharap bahwa Anda memiliki orang-orang yang percaya dalam mencoba membuat kode sendiri. Dalam situasi itu saya akan menganggap komentar sebagai berlebihan.

Untuk percakapan yang menarik tentang kelebihan dan kekurangan dari komentar, lihat http://www.perlmonks.org/index.pl?node_id=65153 untuk percakapan lama yang saya ikuti. (Catatan, pada saat yang sama kami melakukan percakapan itu, ada satu set obrolan pribadi yang lebih ramah. Saya selalu menyesali bahwa hanya separuh lebih negatif dari percakapan itu adalah publik.) Pendapat saya tidak lagi sama persis dengan apa yang saya pikirkan saat itu. , tapi saya masih berpikir bahwa percakapan itu memiliki makanan yang berharga untuk dipikirkan.

Saya menemukan bahwa pertanyaan ini banyak muncul, dan seringkali memiliki semangat keagamaan tentang hal itu. Ini pendapat saya tentang itu ...

Di dunia yang ideal, pernyataan berikut dapat dibuat:

Kode harus ditulis sedemikian rupa, sehingga logika dapat diikuti tanpa perlu komentar.

OKE, ini cukup adil, tetapi masalahnya adalah kita tidak hidup di dunia yang ideal. Ada beberapa masalah dengan mencapai pernyataan ideal ini.

1. Pemrogram sering kali bukan ahli dalam industri yang sedang mereka pemrograman. Cukup mudah untuk memahami suatu fungsi seperti startEngine(Car car)(kebanyakan) setiap orang dapat memahami apa yang ditanyakan di sini. Tetapi pindah ke dunia nyata, dan segalanya menjadi sedikit lebih kabur. Sebagai contoh, fungsinya getSess(String tid, String aid)akan sangat dimengerti oleh seorang insinyur transportasi yang memahami sistem DWDM, tetapi dapat memberikan tantangan bagi programmer baru yang baru saja dimasukkan ke dalam proyek. Komentar yang ditempatkan dengan baik dapat membantu memudahkan transisi untuk memahami kode secara tepat waktu.

2. Pemrogram yang diminta untuk mempertahankan kode sering kali tidak terampil seperti arsitek asli kode. Pemrogram asli mungkin cukup terampil untuk menulis algoritma yang cepat, ringkas, dan efisien untuk menyelesaikan tugas tertentu. Tetapi programmer bertugas untuk mempertahankan kode yang mungkin berjuang dengan mencoba memahami apa yang sedang terjadi. Komentar yang ditempatkan dengan baik dapat membantu memudahkan transisi untuk memahami kode secara tepat waktu.

3. Berapa kali Anda menulis sedikit kode, yang kemudian Anda kesulitan memahami mengapa Anda melakukan itu, atau bahkan apa yang Anda coba capai? Kita semua melakukan itu dari waktu ke waktu. Memecahkan masalah, dan menghasilkan solusi yang mudah diikuti untuk suatu masalah seringkali merupakan dua pola pikir yang berbeda. Kecuali jika Anda adalah orang yang bisa menulis kode dengan sempurna, Anda sering membuat kesalahan langkah dengan kode Anda. Anda mungkin juga tidak dapat kembali ke kode ini untuk sementara waktu. Komentar yang ditempatkan dengan baik dapat membantu memudahkan transisi untuk memahami kode secara tepat waktu.

4. Situasi unik memerlukan penjelasan. Misalnya seorang programmer mungkin bertanya-tanya mengapa jeda 100ms dimasukkan ke dalam sedikit kode yang berkomunikasi dengan perangkat DWDM. Memberi tahu pemrogram berikutnya bahwa jeda diperlukan karena perangkat lambat dalam penggunaannya, dan mungkin melewatkan perintah akan menjadi sedikit informasi berharga untuk dimiliki. Komentar yang ditempatkan dengan baik dapat membantu memudahkan transisi untuk memahami kode secara tepat waktu.

Kode yang ditulis dengan baik, "mendokumentasikan sendiri" adalah kegembiraan untuk ditemukan. Kode yang ditulis dengan baik, "mendokumentasikan sendiri", dengan komentar informatif dan ditempatkan dengan baik adalah anugerah, dan penemuan yang sangat langka.

Hanya untuk memberikan argumen di setiap sisi dari pertanyaan awal:

Ya, kode mendokumentasikan diri. Variabel, metode, dan nama kelas semuanya dapat dibuat agar mudah dibaca dan dipahami sehingga ini adalah bentuk dokumentasi diri. Mungkin ada sesuatu dalam gaya kode yang memberikan dokumentasi XML pada akhirnya yang dianggap sebagai prosedur standar. Dengan kata lain, ini adalah bagian dari tugas pengembang untuk menyediakan dokumentasi yang dapat dicampur dengan kode.

Tidak, kode tidak mendokumentasikan diri. Keputusan bisnis yang dibuat, pilihan desain yang dibuat, dan faktor-faktor lain tidak akan muncul di baris kode dan harus dituliskan di luar basis kode. Jadi dokumentasi eksternal diperlukan dan ini adalah contohnya.

Poin bertanya: Apakah Anda akan memberikan jawaban parsial dengan mengakui keterbatasan jawaban atau akankah Anda secara membungkuk bersandar pada pihak mana pun yang Anda yakini sebagai praktik yang lebih baik? Seberapa banyak keyakinan yang Anda miliki dalam jawaban Anda jika itu adalah ya atau tidak? Itu bisa dilihat sebagai pertanyaan yang menegangkan yang dirancang untuk membangkitkan seseorang yang mungkin menjawab, "Apa ...? Itu pertanyaan paling bodoh yang pernah Anda tanyakan kepada saya. Saya menolak untuk menjawab itu dengan alasan bahwa itu menghina kecerdasan saya melampaui keyakinan! " sebagai jawaban yang agak sombong dan angkuh sehingga saya bisa membayangkan beberapa orang memberikan jawaban dengan nada itu.

Jelas dia adalah seorang programmer yang bisa membaca dalam gaya Knuth. Untuk seorang murid LP kode harus mendokumentasikan diri agar valid. Jadi satu-satunya jawaban yang mungkin adalah "ya".

Masalahnya di sini adalah bahwa tidak ada banyak bahasa pemrograman melek dan tidak ada yang saya ketahui dalam penggunaan komersial luas. Jadi itu akan menjadi posisi niche di suatu tempat.

Saya rasa apa yang mungkin dicari pewawancara adalah: "Bagaimana Anda menulis kode dokumentasi diri?" dengan tersirat "Apa sikap Anda terhadap dokumentasi?"

Saya pergi ke kuliah yang sangat inspirasional oleh seorang pria bernama Robert C Martin suatu ketika di mana dia berbicara tentang bab 'metode menulis' dari bukunya, Clean Code.

Dia jelas menyajikan sedikit posisi purist, tetapi saya menerima sarannya bahwa ketika Anda memotong kode Anda menjadi metode yang dapat digunakan kembali dan menggunakan trik sederhana seperti:

• Menyimpan semua pernyataan dalam suatu metode pada tingkat abstraksi yang sama
• Menarik keluar isi dari kondisi aliran kontrol atau blok loop ke panggilan metode
• Ketika Anda menemukan diri Anda memberikan parameter yang sama ke beberapa metode di kelas, pisahkan kelas baru
• Dan trik sederhana seperti mengganti ekspresi boolean samar dengan panggilan metode
• dll ...

Anda berakhir dengan kode yang dapat dibaca dan sedikit mendokumentasikan diri sendiri (selama Anda berusaha keras untuk memberikan nama yang ringkas dan deskriptif) yang lebih mudah dipahami dan dipelihara.

Saya telah menemukan hal-hal yang sangat membantu, tetapi membutuhkan pengetahuan tentang pola desain untuk melakukannya dengan baik dan Anda pasti perlu melengkapi pendekatan dengan dokumentasi metode kelas dan tingkat tinggi.

Biasanya kode dokumentasi diri mengacu pada praktik menggunakan konvensi penamaan untuk variabel, fungsi, dll. Sehingga tujuan dari kode itu jelas. Jadi, tidak ada kode dengan sendirinya yang tidak mendokumentasikan diri. Saya tidak mengerti apa yang Anda maksudkan di paragraf ketiga. Tampaknya tidak ada hubungannya dengan kode dokumentasi diri.

Jack Reeves membuat argumen yang meyakinkan bahwa kode itu dirancang . Sejauh menyangkut banyak kode sebenarnya adalah satu-satunya "dokumen" yang memberitahu Anda apa yang sistem lakukan. Segala sesuatu yang lain membusuk sebagai sistem hidup cenderung melayang semakin jauh dari sistem yang dirancang. Bahkan jika Anda membuat dokumen dari kode (seperti yang dapat dilakukan oleh banyak alat UML saat ini), itu masih hanya dokumentasi sistem yang akurat pada saat itu .

Jadi kode ya mendokumentasikan diri. Seberapa baik didokumentasikan adalah pertanyaan yang sama sekali berbeda.

Ketika saya menjadi lebih berpengalaman, saya telah belajar bahwa jawaban sebenarnya adalah bahwa kode plus lingkungan pembaca menentukan tingkat dokumentasi diri.

Untuk meminimalkan perbedaan antara lingkungan pembaca dan lingkungan penulis, kami menambahkan komentar. Semakin banyak komentar yang dibutuhkan, biasanya semakin sedikit pengalaman penulis. Ada esai yang luar biasa menggambarkan aspek pengembangan perangkat lunak ini, tetapi saya tidak ingat siapa yang menulisnya atau di mana saya menemukannya.

Saya tahu jawaban kebanyakan orang untuk pertanyaan itu adalah "tidak," tetapi saya akan mengatakan ya. Jika saya ditanyai dalam wawancara untuk suatu pekerjaan, saya masih akan menjawab ya.

Saya telah mengerjakan banyak proyek berbeda dengan sumber terbuka dan tertutup. Mereka berkisar pada dokumentasi dari komentar sederhana yang tersisa sebagai catatan programmer hingga dokumentasi API lengkap. Meskipun dokumentasi API bisa menjadi hebat, pada akhirnya saya selalu mencapai situasi di mana dokumentasi bahasa tertulis tidak cukup untuk menentukan perilaku aktual kode. Saya akhirnya melihat kode sumber, merekayasa balik aplikasi, atau mengganggu pengembang dengan akses sumber untuk melihat kode sumber dan menentukan lebih lanjut.

Bagi saya, kode itu adalah dokumentasi utama. Tidak peduli seberapa banyak Anda menulis dengan kata-kata apa yang akan dilakukan suatu program, perilaku yang tepat ditentukan oleh kode.

Saya setuju bahwa ketika menulis kode, Anda harus mencoba membuat kode Anda sesering mungkin menggambarkannya. Namun seperti yang telah disebutkan orang lain, hampir tidak mungkin dalam program yang kompleks untuk sepenuhnya menggambarkan segala sesuatu yang dilakukan kode. Saya tidak menentang komentar, pada kenyataannya saya menemukan bahwa dengan komentar yang baik dapat lebih mudah untuk membaca kode, meskipun kode itu dapat menjelaskan dirinya sendiri tanpa komentar yang membaca bahasa Inggris atau beberapa bahasa lisan hampir selalu lebih mudah.

Saya telah menemukan bahwa dokumentasi yang paling berguna hampir tidak pernah komentar. Sebagian besar proyek yang saya kerjakan baru-baru ini menyertakan wiki yang mencakup semua bagian yang berbeda, bagaimana mereka terhubung. Saya mencoba menjelaskan apa yang ada di pikiran saya ketika saya menulis kode sehingga orang lain tidak akan merusak kode saya karena mereka tidak mengerti mengapa. Ini juga dapat membantu orang lain memperbaiki kode dengan lebih percaya diri. Saya sering menemukan diri saya ragu-ragu untuk kode refactor karena saya tidak pernah tahu apa yang bisa merusak dan tidak ada penjelasan. Bahkan jika Anda adalah satu-satunya orang yang mengerjakan proyek saya jamin dalam satu atau dua tahun Anda akan lupa mengapa Anda melakukan sesuatu bahkan jika itu adalah kode yang paling indah, Anda masih bisa melupakan mengapa itu ada.

Tentu, jika Anda punya waktu tak terbatas. Saya telah menghabiskan 25+ tahun mendokumentasikan kode untuk pengembang lain. Posisi saya selalu bahwa saya mencoba menjelaskan sesuatu sehingga pengembang lain dapat melakukannya dalam 5 menit, ketika mereka hanya dapat memeriksa kode dan mencari tahu dalam setengah jam. Jika saya menyelamatkan semua orang yang melihat metode itu 25 menit, maka saya sudah melakukan pekerjaan saya.

Saya pikir diagram kelas harus selalu digunakan untuk mendokumentasikan kode. Saya tidak berpikir bahwa jika Anda melihat kode secara langsung, Anda dapat melihat arsitektur lengkap. Saya setuju bahwa jika Anda telah menulis kode sendiri atau mengerjakannya untuk waktu yang lama maka Anda dapat mengerti tetapi setiap kali permintaan baru muncul setiap kali Anda perlu melihat kode dan mencari di mana menambahkan kode baru ini.

Apa yang kami lakukan di perusahaan kami adalah memiliki tampilan diagram kelas dari proyek kami. Kami tidak benar-benar menghabiskan waktu memodelkan tetapi hanya menggunakan diagram kelas untuk memvisualisasikan kode setelah rekayasa terbalik. Jika kode berubah maka ada mekanisme penggabungan dan diagram kelas saya selalu diperbarui.

Yang fantastis adalah bisa menambahkan komentar, kendala ke dalam diagram selain java doc. Kami membalikkan proyek, lalu membuat model dan akhirnya mengekstrak tampilan dari model yang ditampilkan sebagai diagram kelas UML. Saya tidak kode pada tahap ini tetapi mendapatkan cetak biru dari arsitektur kode dan bekerja di atasnya untuk membuat atau memperluas arsitektur saya saat ini. Jika saya suka maka saya menekan tombol dan kode saya yang ada digabung dengan diagram saya. Maksud saya menggabungkan dan tentu saja tidak menghasilkan kode lengkap. Hanya delta antara kode yang ada dan diagram saya yang ditulis, bukan kode lengkap setiap kali.

Saya telah belajar selama bertahun-tahun, memiliki gelar master dan masih kode tetapi saya tidak ingin hanya menjadi penulis java dan ingin menggunakan otak saya sedikit lebih. Pandangan UML memberi saya apa yang saya butuhkan untuk berpikir tentang arsitektur saya, berkomunikasi dengan anggota tim lain dan membuat arsitektur yang lebih baik tanpa menggunakan pengembangan Model Driven tetapi hanya delta antara kode yang ditulis secara manual yang ada dan secara grafis membuat diagram kelas. Saya membuat arsitektur pada level kode, lalu membalikkannya dan melihat modelnya. Saya membuat tampilan dan mencoba untuk meningkatkan arsitektur saya secara langsung dalam kode, kemudian membalikkan lagi dan melihat apa yang dilakukan dll ... Ini adalah iterasi permanen tanpa model yang menghasilkan generasi kode tetapi sinkronisasi langsung atau menggabungkan antara kode dan UML. Yang saya suka adalah bahwa kode mendorong UML dan tentu saja tidak sebaliknya.