Ngopi #20. Apa kode warisan lan cara nggarap. Piranti sing nggawe dokumentasi teknis luwih gampang

Apa kode warisan lan cara nggarap

Sumber: Dou Cepet lan mengko, programmer mbokmenawa kudu nemoni kode warisan. Kanggo nggampangake akibat saka kenalan iki, aku wis milih sawetara tips praktis lan conto saka pengalamanku dhewe - utamane, nggarap sistem Jawa warisan.

Fitur Warisan

Warisan minangka kode wong liya, sing asring banget nggegirisi sing umume ora jelas cara nggarap. Lan yen sampeyan kudu nggarap sistem warisan, saliyane kode lawas, sampeyan uga bakal nemoni:

• karo teknologi outdated;
• arsitektur heterogen;
• lack utawa malah lengkap anané saka dokumentasi.

Nyatane, kode warisan ora medeni, lan iki sebabe: yen sistem wis urip sepuluh taun lan isih bisa digunakake, mula ana gunane. Mungkin nggawe dhuwit apik (ora kaya wiwitan pungkasan). Kajaba iku, kode iki relatif dipercaya yen bisa urip ing produksi nganti suwe. Mulane, owah-owahan kasebut kudu ditindakake kanthi ati-ati. Kaping pisanan, sampeyan kudu ngerti rong perkara:

1. Kita ora bisa ngurmati sistem sing nggawe jutaan utawa diakses ewonan wong saben dina. Ora ketompo carane kurang ditulis, kode njijiki iki slamet kanggo produksi lan dianggo 24/7.

2. Wiwit sistem iki ndadekke dhuwit nyata, nggarap iku teka karo tanggung jawab gedhe. Iki dudu wiwitan, nanging ana sing bakal ditindakake pangguna sesuk. Iki uga nyebabake biaya kesalahan sing dhuwur banget, lan titik ing kene ora ana ing klaim klien, nanging ing kahanan nyata.

Reverse engineering

Kanggo sukses nggarap kode warisan, sampeyan kudu nggunakake teknik reverse engineering. Pisanan, sampeyan kudu maca kode kasebut kanthi teliti kanggo ngerti cara kerjane. Iki wajib, amarga kemungkinan besar kita ora duwe dokumentasi. Yen kita ora ngerti sepur pikirane penulis, kita bakal nggawe owah-owahan kanthi akibat sing ora bisa ditebak. Kanggo nglindhungi dhewe saka iki, sampeyan uga kudu delve menyang kode jejer. Lan ing wektu sing padha mindhah ora mung ing ambane, nanging uga ing ambane. Ing endi metode kasebut diarani kesalahan? Saka ngendi asale kode sing diarani? Ing proyek warisan, "hierarki telpon" lan "hierarki jinis" digunakake luwih asring tinimbang liyane. Sampeyan kudu nglampahi akeh wektu karo debugger: pisanan, kanggo nemokake kasalahan, lan liya, kanggo ngerti carane kabeh bisa. Minangka kanggo dokumentasi, iku ora bakal dadi idea ala kanggo Resor kanggo arkeologi industri. Bisa migunani banget kanggo nggali dokumentasi lawas ing endi wae lan ngobrol karo wong sing ngelingi carane kode sing diwarisake ditulis. Nggunakake teknik kasebut, cepet utawa mengko sampeyan bakal mulai ngerti kode kasebut. Nanging kanggo nyegah usaha sampeyan dadi boros, sampeyan kudu langsung nyathet asil riset. Kanggo nindakake iki, aku nyaranake nggambar diagram blok utawa diagram urutan. Mesthi, sampeyan bakal kesed, nanging sampeyan kudu nindakake iki, yen ora, sajrone nem wulan tanpa dokumentasi, sampeyan bakal ngeduk kode iki kaya sing sepisanan.

Aja nulis maneh kode

Wangsulan: Bab ingkang paling penting ing proses pembangunan iku kanggo ngalahake dhewe ing wektu lan ora nyoba kanggo nulis ulang kabeh kode saka ngeruk. Kira-kira pirang-pirang taun wong sing dibutuhake. Ora mungkin pelanggan pengin mbuwang dhuwit akeh kanggo nindakake maneh sing wis bisa digunakake. Iki ditrapake ora mung kanggo sistem kanthi sakabehe, nanging uga kanggo bagean apa wae. Mesthi, dheweke bisa menehi sampeyan seminggu kanggo ngerteni kabeh, lan minggu liyane kanggo ndandani. Nanging padha ora kamungkinan kanggo menehi rong sasi kanggo nulis bagéan saka sistem maneh. Nanging, ngleksanakake fungsi anyar kanthi gaya sing padha karo kode liyane. Ing tembung liya, yen kode wis lawas, sampeyan ora kudu digodha nggunakake teknologi anyar sing apik: kode kasebut bakal angel diwaca. Contone, sampeyan bisa nemokke kahanan kaya kita wis: bagéan saka sistem ditulis ing Spring MVC, lan bagean ditulis ing servlets gundhul. Lan yen ing bagean sing ditulis ing servlets, ana sing kudu ditambahake, banjur ditambahake kanthi cara sing padha - ing servlets.

Ngormati kapentingan bisnis

Sampeyan kudu eling yen tugas apa wae ditemtokake, pisanan, kanthi nilai bisnis. Yen sampeyan ora mbuktekaken pelanggan perlu kanggo owah-owahan tartamtu saka sudut pandang bisnis, owah-owahan iki ora bakal kelakon. Lan kanggo gawe uwong yakin customer, sampeyan kudu nyoba kanggo ngadeg ing panggonan lan ngerti kapentingan. Ing tartamtu, yen sampeyan pengin refactor mung amarga kode hard kanggo maca, sampeyan ora bakal diijini kanggo nindakaken, lan sampeyan kudu manggon karo. Yen sampeyan pancene ora bisa nanggung, sampeyan bisa ngatur maneh kode kanthi tenang lan sethithik, nyebarake karya ing tiket bisnis. Utawa gawe uwong yakin customer sing iki, contone, bakal nyuda wektu sing dibutuhake kanggo nemokake kasalahan, lan mulane pungkasanipun nyuda biaya.

Tes

Cetha yen tes perlu ing proyek apa wae. Nanging nalika nggarap sistem warisan, perhatian khusus kudu dibayar kanggo nyoba uga amarga pengaruh owah-owahan sing ditindakake ora mesthi bisa diprediksi. Sampeyan mbutuhake paling ora akeh penguji minangka pangembang, yen ora, sampeyan kudu apik banget ing otomatisasi. Ing proyek kita, tes kalebu fase ing ngisor iki:

1. Verifikasi, nalika fungsi dileksanakake saka fitur wis dicenthang ing cabang kapisah.
2. Stabilisasi, nalika cabang rilis dicenthang ing ngendi kabeh fitur digabungake.
3. Sertifikasi, nalika perkara sing padha ditindakake maneh ing kasus uji sing rada beda ing lingkungan sertifikasi sing cedhak karo produksi babagan karakteristik lan konfigurasi hardware.

Lan mung sawise liwat kabeh telung fase iki kita bisa nggawe release. Sapa wae sing ngira yen sertifikasi minangka fase ekstra, amarga kabeh wis dijlentrehake ing tahap stabilisasi, nanging pengalaman kita nuduhake manawa ora kaya ngono: kadhangkala sajrone tes regresi, sing ditindakake ing babak kaping pindho ing mesin liyane, soko piye wae. iku bakal metu.

Formalize DevOps lan Rilis

Prosedur release bisa, contone, kaya ing ngisor iki. Nalika pembangunan rampung lan loro utawa telung fase tes wis rampung, kita nulis email menyang tim DevOps 36 jam sadurunge wektu rilis samesthine. Sawise iki, kita nelpon tim devops lan ngrembug kabeh owah-owahan ing lingkungan (kita ngandhani kabeh owah-owahan ing database lan konfigurasi). Kanggo saben owah-owahan kita duwe dokumen (tiket ing Jira). Banjur, sajrone rilis, kabeh wong sing melu iki ngumpul, lan saben wong ngomong apa sing ditindakake saiki: "We upload database," "We restarted such and such servers," "We went to run regression tests in the production environment. ” Yen ana sing salah, prosedur rollback rilis diluncurake, persis diterangake ing dokumen rilis asli - tanpa dokumen kasebut, kita mesthi bakal lali utawa bingung.

Kontrol kualitas kode

Lan pungkasane, review kode minangka praktik sing sakperangan alesan ora digunakake ing kabeh proyek. Apik banget yen saben potongan kode dideleng luwih saka siji wong. Malah ing tim sing kuwat banget, sawetara kewan omo tansah ditemokake sajrone proses review kode, lan yen sawetara wong ndeleng, jumlah bug sing diidentifikasi mundhak. Kajaba iku, kadhangkala reviewer katelu utawa kaping papat nemokake sing paling ala.

Piranti sing nggawe dokumentasi teknis luwih gampang

Sumber: Dzone Umume programer ora seneng nulis dokumentasi teknis. Pakar psikologi Gerald Weinberg malah nyebutake dokumentasi "minyak jarak pemrograman": pangembang seneng maca, nanging dheweke ora seneng nulis dhewe. A lack saka panuntun dhumateng utawa roadmap kothong nyebabake lack informasi bab carane macem-macem bagean saka piranti lunak bisa digunakake. Iki pungkasane nambah pengalaman kanggo pangguna pungkasan kode amarga, tanpa dokumentasi, dheweke ora bisa ngandelake akurasi lan migunani produk kasebut. Kanggo nggawe luwih gampang kanggo programer kanggo mbentuk pakulinan nulis dokumentasi, Aku nyaranake mbayar manungsa waé kanggo papat alat banget sing saiki kasedhiya kanggo meh everyone.

Kaca GitHub

Saiki ora ana pangembang siji sing ora duwe pengalaman nggarap GitHub. Iki uga minangka papan sing apik kanggo programer sing mbutuhake papan kanggo nyimpen dokumentasi. Akeh wong nggunakake Readme standar ing basis kode kanggo nyedhiyakake pangguna kanthi cara sing gampang, nanging iki ora mung siji-sijine cara kanggo nggawe dokumentasi ing GitHub. Kanthi GitHub Pages , sampeyan entuk luwih saka mung hosting kanggo kaca proyek sampeyan, kalebu dokumentasi lan tutorial. Sampeyan entuk kemampuan kanggo sesambungan langsung karo kabeh repositori GitHub, ngidini pangembang nganyari dokumentasi kanthi cara sing padha nganyari kode. Kajaba iku, sampeyan bisa nggunakake Jekyll ing kene - mbantu sampeyan ngowahi markup dadi teks biasa utawa dadi kaca web lengkap.

Maca Docs

Minangka jeneng kasebut, Read the Docs nyedhiyakake pangembang platform kanggo nyimpen lan maca dokumentasi. Layanan kasebut kaya GitHub Pages: programer bisa ngowahi dokumentasi saka sistem kontrol versi favorit, kalebu Git, Bazaar, Mercurial lan liya-liyane. Versi otomatis lan nggawe kaca uga didhukung. Sisih paling apik saka Read Docs yaiku keluwesan. Ndhukung webhooks supaya sampeyan bisa ngotomatisasi akeh proses nggawe dokumen. Iki minangka pengirit wektu sing akeh banget kanggo tugas sing paling akeh programer ora pengin apa-apa. Kajaba iku, kabeh sing di-host ing platform kasedhiya kanggo masarakat umum ing macem-macem format, kalebu PDF, HTML siji-halaman, lan malah format e-buku. Layanan kasebut njupuk bagean penting saka rutinitas supaya dokumentasi tetep anyar.

Tetra

Tettra ora mung platform kanggo nyimpen dokumentasi piranti lunak, nanging basis kawruh lengkap. Kerjane apik banget nalika proyek melu klompok gedhe coders sing nggarap macem-macem piranti lunak. Tettra bisa digunakake kanggo nyathet jawaban kanggo pitakonan umum.

Apiary

Apa sing ndadekake Apiary migunani kanggo pangembang yaiku nyatane nindakake tugas sing apik kanggo mbantu dokumentasi API. Platform kasebut ngidini pangguna nulis dokumentasi ing Markdown , kalebu panggilan API mock. Apiary uga ngidini sampeyan nyoba lan prototipe unsur API. Ing tembung liyane, iku alat dokumentasi lan platform testing ing sak panggonan.