Rehat kopi #20. Apakah itu kod warisan dan cara bekerja dengannya. Alat yang memudahkan penulisan dokumentasi teknikal

Apakah itu kod warisan dan cara bekerja dengannya

Sumber: Dou Lambat laun, seorang pengaturcara mungkin perlu menemui kod warisan. Untuk meringankan akibat perkenalan ini, saya telah memilih beberapa petua dan contoh praktikal daripada pengalaman saya sendiri - khususnya, bekerja dengan sistem Java warisan.

Ciri Legasi

Warisan ialah kod orang lain, yang selalunya sangat mengerikan sehingga tidak jelas cara menggunakannya. Dan jika anda perlu bekerja dengan sistem warisan, sebagai tambahan kepada kod lama, anda juga akan menghadapi:

• dengan teknologi ketinggalan zaman;
• seni bina heterogen;
• kekurangan atau ketiadaan lengkap dokumentasi.

Sebenarnya, kod warisan tidak begitu menakutkan, dan inilah sebabnya: jika sistem telah hidup selama sepuluh tahun ini dan masih berfungsi, maka ia mempunyai sedikit kegunaan. Mungkin ia menghasilkan wang yang baik (tidak seperti permulaan terakhir anda). Selain itu, kod ini agak boleh dipercayai jika ia dapat bertahan dalam pengeluaran selama ini. Oleh itu, perubahan padanya mesti dibuat dengan berhati-hati. Pertama sekali, anda perlu memahami dua perkara:

1. Kita tidak boleh tidak menghormati sistem yang menghasilkan berjuta-juta atau diakses oleh beribu-ribu orang sehari. Tidak kira betapa buruknya ia ditulis, kod menjijikkan ini kekal sehingga pengeluaran dan berfungsi 24/7.

2. Memandangkan sistem ini membawa wang sebenar, bekerja dengannya datang dengan tanggungjawab yang besar. Ini bukan permulaan, tetapi sesuatu yang pengguna akan bekerjasama esok. Ini juga membayangkan kos ralat yang sangat tinggi, dan perkara di sini bukan dalam tuntutan pelanggan, tetapi dalam keadaan sebenar.

Kejuruteraan terbalik

Untuk berjaya menggunakan kod warisan, anda perlu menggunakan teknik kejuruteraan terbalik. Pertama, anda perlu membaca kod dengan teliti untuk memahami dengan tepat cara ia berfungsi. Ini adalah wajib, kerana kemungkinan besar kami tidak akan mempunyai dokumentasi. Jika kita tidak memahami aliran pemikiran penulis, kita akan membuat perubahan dengan akibat yang tidak dapat diramalkan. Untuk melindungi diri anda daripada ini, anda juga perlu menyelidiki kod bersebelahan. Dan pada masa yang sama bergerak bukan sahaja secara luas, tetapi juga secara mendalam. Di manakah kaedah dipanggil dengan ralat? Dari manakah kod yang memanggilnya? Dalam projek warisan, "hierarki panggilan" dan "hierarki jenis" digunakan lebih kerap daripada yang lain. Anda perlu menghabiskan banyak masa dengan penyahpepijat: pertama, untuk mencari ralat, dan kedua, untuk memahami cara semuanya berfungsi. Bagi dokumentasi, bukanlah idea yang buruk untuk menggunakan arkeologi industri. Ia boleh menjadi sangat berguna untuk menggali dokumentasi lama di suatu tempat dan bercakap dengan mereka yang mengingati cara kod yang anda warisi ditulis. Menggunakan teknik ini, lambat laun anda akan mula memahami kod tersebut. Tetapi untuk mengelakkan usaha anda daripada menjadi sia-sia, anda mesti segera mendokumenkan hasil penyelidikan anda. Untuk melakukan ini, saya mengesyorkan melukis gambar rajah blok atau gambar rajah jujukan. Sudah tentu, anda akan malas, tetapi anda pasti perlu melakukan ini, jika tidak dalam enam bulan tanpa dokumentasi anda akan menggali kod ini seperti kali pertama.

Jangan tulis semula kod

Perkara yang paling penting dalam proses pembangunan adalah untuk mengalahkan diri anda tepat pada masanya dan tidak cuba menulis semula keseluruhan kod dari awal. Anggarkan berapa tahun manusia yang diperlukan. Tidak mungkin pelanggan ingin membelanjakan begitu banyak wang untuk membuat semula sesuatu yang telah berjaya. Ini terpakai bukan sahaja kepada sistem secara keseluruhan, tetapi juga untuk mana-mana bahagiannya. Sudah tentu, mereka mungkin memberi anda masa seminggu untuk memikirkan segala-galanya, dan seminggu lagi untuk membetulkan sesuatu. Tetapi mereka tidak mungkin memberi anda dua bulan untuk menulis sebahagian daripada sistem itu semula. Sebaliknya, laksanakan fungsi baharu dalam gaya yang sama seperti kod yang lain. Dalam erti kata lain, jika kod itu sudah lama, anda tidak seharusnya tergoda untuk menggunakan teknologi baharu yang cantik: kod tersebut kemudiannya akan menjadi sangat sukar untuk dibaca. Sebagai contoh, anda mungkin menghadapi situasi seperti yang kami alami: sebahagian daripada sistem ditulis dalam Spring MVC, dan sebahagian ditulis dalam servlet kosong. Dan jika dalam bahagian yang ditulis dalam servlets, sesuatu yang lain perlu ditambah, maka kami menambahnya dengan cara yang sama - dalam servlets.

Hormati kepentingan perniagaan

Perlu diingat bahawa apa-apa tugas ditentukan, pertama sekali, oleh nilai untuk perniagaan. Jika anda tidak membuktikan kepada pelanggan keperluan untuk perubahan tertentu dari sudut perniagaan, perubahan ini tidak akan berlaku. Dan untuk meyakinkan pelanggan, anda mesti cuba berdiri di tempatnya dan memahami minatnya. Khususnya, jika anda ingin memfaktorkan semula hanya kerana kod itu sukar dibaca, anda tidak akan dibenarkan melakukannya, dan anda perlu menjalaninya. Jika anda benar-benar tidak tahan, anda boleh menyusun semula kod secara senyap dan sedikit demi sedikit, menyebarkan kerja merentasi tiket perniagaan. Atau meyakinkan pelanggan bahawa ini, sebagai contoh, akan mengurangkan masa yang diperlukan untuk mencari kesilapan, dan oleh itu akhirnya mengurangkan kos.

Ujian

Adalah jelas bahawa ujian adalah perlu dalam mana-mana projek. Tetapi apabila bekerja dengan sistem warisan, perhatian khusus mesti diberikan kepada ujian juga kerana kesan perubahan yang dibuat tidak selalu dapat diramalkan. Anda memerlukan sekurang-kurangnya seberapa banyak penguji sebagai pembangun, jika tidak, anda harus sangat mahir dalam automasi. Dalam projek kami, ujian terdiri daripada fasa berikut:

1. Pengesahan, apabila fungsi yang dilaksanakan bagi sesuatu ciri disemak dalam cawangan berasingan.
2. Penstabilan, apabila cawangan keluaran diperiksa di mana semua ciri digabungkan bersama.
3. Pensijilan, apabila perkara yang sama dijalankan semula pada kes ujian yang sedikit berbeza dalam persekitaran pensijilan yang sedekat mungkin dengan pengeluaran dari segi ciri dan konfigurasi perkakasan.

Dan hanya selepas melalui ketiga-tiga fasa ini barulah kita boleh membuat pelepasan. Seseorang mungkin berpendapat bahawa pensijilan adalah fasa tambahan, kerana semuanya telah dijelaskan pada peringkat penstabilan, tetapi pengalaman kami menunjukkan bahawa ini tidak begitu: kadangkala semasa ujian regresi, yang dijalankan untuk pusingan kedua pada mesin lain, sesuatu entah bagaimana ia akan keluar.

Rasmikan DevOps dan Keluarkan

Prosedur pelepasan boleh, sebagai contoh, seperti berikut. Apabila pembangunan selesai dan dua atau tiga fasa ujian telah selesai, kami menulis e-mel kepada pasukan DevOps 36 jam sebelum masa keluaran yang dijangkakan. Selepas ini, kami memanggil pasukan devops dan membincangkan semua perubahan kepada persekitaran (kami memberitahu mereka tentang semua perubahan dalam pangkalan data dan konfigurasi). Untuk setiap perubahan kami mempunyai dokumen (tiket di Jira). Kemudian, semasa keluaran, semua orang yang terlibat dalam perkara ini berkumpul dan semua orang berkata apa yang mereka lakukan sekarang: "Kami memuat naik pangkalan data," "Kami memulakan semula pelayan itu dan itu," "Kami pergi untuk menjalankan ujian regresi dalam persekitaran pengeluaran. ” Jika berlaku kesilapan, prosedur rollback keluaran dilancarkan, betul-betul diterangkan dalam dokumen keluaran asal - tanpa dokumen sedemikian kita pasti akan melupakan sesuatu atau menjadi keliru.

Kawalan kualiti kod

Dan akhirnya, semakan kod adalah amalan yang atas sebab tertentu tidak digunakan dalam semua projek. Sangat bagus jika setiap keping kod disemak oleh lebih daripada seorang. Walaupun dalam pasukan yang sangat kuat, sesetengah pepijat sentiasa ditemui semasa proses semakan kod, dan jika beberapa orang melihatnya, bilangan pepijat yang dikenal pasti meningkat. Selain itu, kadangkala pengulas ketiga atau keempat mendapati perkara yang paling teruk.

Alat yang memudahkan penulisan dokumentasi teknikal

Sumber: Dzone Kebanyakan pengaturcara tidak suka menulis dokumentasi teknikal. Pakar psikologi Gerald Weinberg malah memanggil dokumentasi "minyak kastor pengaturcaraan": pemaju suka membacanya, tetapi mereka tidak suka menulisnya sendiri. Kekurangan panduan atau peta jalan kosong mengakibatkan kekurangan maklumat tentang cara bahagian perisian yang berbeza berfungsi. Ini akhirnya memburukkan lagi pengalaman pengguna akhir kod kerana, tanpa adanya dokumentasi, mereka tidak boleh bergantung pada ketepatan dan kegunaan produk. Untuk memudahkan pengaturcara membentuk tabiat menulis dokumentasi, saya mengesyorkan agar anda memberi perhatian kepada empat alat hebat yang kini tersedia untuk hampir semua orang.

Halaman GitHub

Mungkin tiada seorang pembangun hari ini yang tidak mempunyai pengalaman bekerja di GitHub. Ia juga merupakan tempat yang bagus untuk pengaturcara yang memerlukan tempat untuk menyimpan dokumentasi. Ramai orang menggunakan Readme standard dalam pangkalan kod mereka untuk menyediakan pengguna dengan panduan cara mudah, tetapi ini bukan satu-satunya cara untuk membuat dokumentasi pada GitHub. Dengan GitHub Pages , anda mendapat lebih daripada sekadar pengehosan untuk halaman projek anda, termasuk dokumentasi dan tutorial. Anda mendapat keupayaan untuk berinteraksi secara langsung dengan semua repositori GitHub, membenarkan pembangun mengemas kini dokumentasi dengan cara yang sama mereka mengemas kini kod mereka. Selain itu, anda boleh menggunakan Jekyll di sini - ia membantu anda mengubah penanda anda menjadi teks biasa atau menjadi halaman web yang lengkap.

Baca Dokumen

Seperti namanya, Baca Dokumen menyediakan pemaju dengan platform untuk menyimpan dan membaca dokumentasi. Perkhidmatan ini berfungsi sama seperti Halaman GitHub: pengaturcara boleh membuat perubahan pada dokumentasi daripada sistem kawalan versi kegemaran mereka, termasuk Git, Bazaar, Mercurial dan lain-lain. Versi automatik dan penciptaan halaman juga disokong. Bahagian terbaik Read Docs ialah fleksibilitinya. Ia menyokong webhooks supaya anda boleh mengautomasikan banyak proses penciptaan dokumen. Ini adalah penjimat masa yang besar pada tugas yang kebanyakan pengaturcara tidak mahu lakukan apa-apa. Selain itu, semua yang dihoskan pada platform tersedia untuk orang awam dalam pelbagai format, termasuk PDF, HTML satu halaman dan juga format e-buku. Perkhidmatan ini mengambil bahagian penting dalam kerja rutin untuk memastikan dokumentasi dikemas kini.

Tettra

Tettra bukan sekadar platform untuk menyimpan dokumentasi perisian, tetapi pangkalan pengetahuan yang lengkap. Ia berfungsi dengan baik apabila projek melibatkan sekumpulan besar pengekod yang bekerja pada kepingan perisian yang berbeza. Tettra boleh digunakan untuk mendokumentasikan jawapan kepada soalan biasa.

Apiari

Apa yang menjadikan Apiary sangat berguna untuk pembangun ialah hakikat bahawa ia melakukan tugas yang hebat dalam membantu dengan dokumentasi API. Platform ini membolehkan pengguna menulis dokumentasi mereka dalam Markdown , termasuk panggilan API olok-olok. Apiary juga membolehkan anda menguji dan membuat prototaip elemen API. Dalam erti kata lain, ia adalah alat dokumentasi dan platform ujian di satu tempat.