Coffee break #20. Ano ang legacy code at kung paano gamitin ito. Mga tool na nagpapadali sa pagsulat ng teknikal na dokumentasyon

Ano ang legacy code at kung paano gamitin ito

Pinagmulan: Dou Sa lalong madaling panahon, ang isang programmer ay malamang na makatagpo ng legacy code. Para mapagaan ang mga kahihinatnan ng kakilalang ito, pumili ako ng ilang praktikal na tip at halimbawa mula sa sarili kong karanasan - lalo na, nagtatrabaho sa isang legacy na Java system.

Mga Legacy na Tampok

Ang legacy ay code ng ibang tao, na kadalasan ay napakasama na sa pangkalahatan ay hindi malinaw kung paano ito gagawin. At kung kailangan mong magtrabaho sa isang legacy system, bilang karagdagan sa lumang code, makakatagpo ka rin ng:

• na may hindi napapanahong teknolohiya;
• magkakaibang arkitektura;
• kakulangan o kahit kumpletong kawalan ng dokumentasyon.

Sa katunayan, ang legacy code ay hindi ganoon nakakatakot, at narito kung bakit: kung ang system ay nabuhay sa lahat ng sampung taon na ito at gumagana pa rin, kung gayon ito ay may ilang gamit. Marahil ito ay kumikita ng magandang pera (hindi tulad ng iyong huling pagsisimula). Bukod pa rito, ang code na ito ay relatibong maaasahan kung ito ay nakaligtas sa produksyon nang ganito katagal. Samakatuwid, ang mga pagbabago dito ay dapat gawin nang may pag-iingat. Una sa lahat, kailangan mong maunawaan ang dalawang bagay:

1. Hindi namin maaaring balewalain ang isang sistema na kumikita ng milyun-milyon o naa-access ng libu-libong tao sa isang araw. Gaano man kahirap ang pagkakasulat nito, ang kasuklam-suklam na code na ito ay nanatili sa produksyon at gumagana 24/7.

2. Dahil ang sistemang ito ay nagdadala ng tunay na pera, ang pagtatrabaho dito ay may malaking responsibilidad. Hindi ito isang startup, ngunit isang bagay na gagawin ng mga user bukas. Ipinahihiwatig din nito ang napakataas na halaga ng error, at ang punto dito ay wala sa mga claim ng kliyente, ngunit sa totoong estado ng mga gawain.

Reverse engineering

Upang matagumpay na gumana sa legacy code, kakailanganin mong gumamit ng mga reverse engineering technique. Una, kailangan mong maingat na basahin ang code upang maunawaan nang eksakto kung paano ito gumagana. Ito ay sapilitan, dahil malamang na wala kaming dokumentasyon. Kung hindi natin naiintindihan ang takbo ng pag-iisip ng may-akda, gagawa tayo ng mga pagbabago na may hindi inaasahang kahihinatnan. Upang maprotektahan ang iyong sarili mula dito, kailangan mo ring suriin ang katabing code. At sa parehong oras lumipat hindi lamang sa lawak, kundi pati na rin sa lalim. Saan ang pamamaraan na tinatawag na may error? Saan nagmula ang code na tumatawag dito? Sa isang legacy na proyekto, ang "call hierarchy" at "type hierarchy" ay mas madalas na ginagamit kaysa sa anupaman. Kakailanganin mong gumugol ng maraming oras sa debugger: una, upang makahanap ng mga error, at pangalawa, upang maunawaan kung paano gumagana ang lahat. Tulad ng para sa dokumentasyon, hindi isang masamang ideya na gumamit ng pang-industriyang arkeolohiya. Maaari itong maging lubhang kapaki-pakinabang upang maghukay ng lumang dokumentasyon sa isang lugar at makipag-usap sa mga nakakaalala kung paano isinulat ang code na iyong minana. Gamit ang mga diskarteng ito, maaga o huli ay magsisimula kang maunawaan ang code. Ngunit upang maiwasan ang iyong mga pagsisikap na masayang, dapat mong agad na idokumento ang mga resulta ng iyong pananaliksik. Upang gawin ito, inirerekumenda ko ang pagguhit ng mga block diagram o sequence diagram. Siyempre, magiging tamad ka, ngunit tiyak na kailangan mong gawin ito, kung hindi, sa loob ng anim na buwan nang walang dokumentasyon ay hahanapin mo ang code na ito tulad ng unang pagkakataon.

Huwag muling isulat ang code

Ang pinakamahalagang bagay sa proseso ng pag-unlad ay upang matalo ang iyong sarili sa oras at hindi subukang muling isulat ang buong code mula sa simula. Tantyahin kung gaano karaming tao-taon ang kakailanganin nito. Malamang na ang customer ay gugustuhin na gumastos ng napakaraming pera sa muling paggawa ng isang bagay na gumagana na. Nalalapat ito hindi lamang sa sistema sa kabuuan, kundi pati na rin sa alinmang bahagi nito. Siyempre, maaaring bigyan ka nila ng isang linggo para malaman ang lahat, at isa pang linggo para ayusin ang isang bagay. Ngunit malamang na hindi ka nila bibigyan ng dalawang buwan upang magsulat muli ng bahagi ng system. Sa halip, ipatupad ang bagong pag-andar sa parehong estilo tulad ng natitirang bahagi ng code. Sa madaling salita, kung luma na ang code, hindi ka dapat matuksong gumamit ng mga bagong magagandang teknolohiya: ang naturang code ay magiging napakahirap basahin. Halimbawa, maaari kang makatagpo ng sitwasyong tulad namin: ang bahagi ng system ay nakasulat sa Spring MVC, at ang bahagi ay nakasulat sa mga hubad na servlet. At kung sa isang bahagi na nakasulat sa mga servlet, may iba pang kailangang idagdag, pagkatapos ay idagdag namin ito sa parehong paraan - sa mga servlet.

Igalang ang mga interes sa negosyo

Dapat tandaan na ang anumang mga gawain ay tinutukoy, una sa lahat, sa pamamagitan ng halaga para sa negosyo. Kung hindi mo patunayan sa customer ang pangangailangan para sa ilang partikular na pagbabago mula sa pananaw ng negosyo, hindi mangyayari ang mga pagbabagong ito. At upang kumbinsihin ang customer, dapat mong subukang tumayo sa kanyang lugar at maunawaan ang kanyang mga interes. Sa partikular, kung gusto mong mag-refactor dahil lang sa mahirap basahin ang code, hindi ka papayagang gawin ito, at kailangan mong mabuhay kasama nito. Kung talagang hindi mo ito kayang tiisin, maaari mong muling ayusin ang code nang tahimik at unti-unti, na ikinakalat ang trabaho sa mga tiket ng negosyo. O kumbinsihin ang customer na ito, halimbawa, ay magbabawas sa oras na kinakailangan upang makahanap ng mga error, at samakatuwid ay bawasan ang mga gastos.

Pagsusulit

Malinaw na kailangan ang pagsubok sa anumang proyekto. Ngunit kapag nagtatrabaho sa mga legacy system, dapat ding bigyan ng espesyal na atensyon ang pagsubok dahil hindi palaging nahuhulaan ang epekto ng mga pagbabagong ginawa. Kakailanganin mo ng kahit gaano karaming mga tester gaya ng mga developer, kung hindi, dapat ay napakahusay mo sa automation. Sa aming proyekto, ang pagsubok ay binubuo ng mga sumusunod na yugto:

1. Pag-verify, kapag ang ipinatupad na pagpapagana ng isang tampok ay nasuri sa isang hiwalay na sangay.
2. Pagpapatatag, kapag ang isang release branch ay nasuri kung saan ang lahat ng mga tampok ay pinagsama-sama.
3. Certification, kapag ang parehong bagay ay pinapatakbo muli sa bahagyang magkaibang mga kaso ng pagsubok sa isang certification environment na mas malapit hangga't maaari sa produksyon sa mga tuntunin ng mga katangian ng hardware at configuration.

At pagkatapos lamang na dumaan sa lahat ng tatlong yugtong ito ay makakagawa tayo ng paglabas. Marahil ay iniisip ng isang tao na ang sertipikasyon ay isang karagdagang yugto, dahil ang lahat ay nilinaw na sa yugto ng pag-stabilize, ngunit ang aming karanasan ay nagmumungkahi na hindi ito ganoon: minsan sa panahon ng isang pagsubok sa pagbabalik, na pinapatakbo para sa ikalawang pag-ikot sa isa pang makina, isang bagay sa anumang paraan lalabas ito.

I-formalize ang DevOps at I-release

Ang pamamaraan ng paglabas ay maaaring, halimbawa, ay ang mga sumusunod. Kapag nakumpleto na ang pag-develop at nakumpleto na ang dalawa o tatlong yugto ng pagsubok, sumusulat kami ng email sa koponan ng DevOps 36 na oras bago ang inaasahang oras ng paglabas. Pagkatapos nito, tinatawagan namin ang devops team at tinatalakay ang lahat ng pagbabago sa mga environment (ipinapaalam namin sa kanila ang tungkol sa lahat ng pagbabago sa database at configuration). Para sa bawat pagbabago mayroon kaming isang dokumento (isang tiket sa Jira). Pagkatapos, sa panahon ng pag-release, lahat ng kasangkot dito ay magkakasama-sama, at lahat ay nagsasabi kung ano ang kanilang ginagawa ngayon: "Nag-upload kami ng database," "Nag-restart kami ng ganoon at ganoong mga server," "Nagpunta kami upang magpatakbo ng mga pagsubok sa regression sa kapaligiran ng produksyon. ” Kung may mali, inilunsad ang release rollback procedure, eksaktong inilarawan sa orihinal na dokumento ng release - kung walang ganoong dokumento ay tiyak na makakalimutan natin ang isang bagay o malito.

Kontrolin ang kalidad ng code

At sa wakas, ang pagsusuri ng code ay isang kasanayan na sa ilang kadahilanan ay hindi ginagamit sa lahat ng mga proyekto. Napakaganda kung ang bawat piraso ng code ay susuriin ng higit sa isang tao. Kahit na sa isang napakalakas na team, ang ilang mga bug ay palaging natutuklasan sa panahon ng proseso ng pagsusuri ng code, at kung maraming tao ang tumitingin dito, ang bilang ng mga bug na natukoy ay tataas. Bukod dito, kung minsan ang pangatlo o ikaapat na tagasuri ay nakakahanap ng pinakamasamang bagay.

Mga tool na nagpapadali sa pagsulat ng teknikal na dokumentasyon

Pinagmulan: Dzone Karamihan sa mga programmer ay hindi gustong magsulat ng teknikal na dokumentasyon. Tinawag pa nga ng dalubhasa sa sikolohiya na si Gerald Weinberg ang dokumentasyon na "ang langis ng castor ng programming": gustong-gusto ng mga developer na basahin ito, ngunit ayaw lang nilang sumulat nito. Ang kakulangan ng gabay o isang blangkong roadmap ay nagreresulta sa kakulangan ng impormasyon tungkol sa kung paano gumagana ang iba't ibang bahagi ng software. Sa huli, pinalala nito ang karanasan para sa mga end user ng code dahil, sa kawalan ng dokumentasyon, hindi sila makakaasa sa katumpakan at pagiging kapaki-pakinabang ng produkto. Upang gawing mas madali para sa mga programmer na mabuo ang ugali ng pagsulat ng dokumentasyon, inirerekumenda kong bigyang pansin ang apat na mahusay na tool na magagamit na ngayon sa halos lahat.

Mga Pahina sa GitHub

Malamang na walang nag-iisang developer ngayon na walang karanasan sa pagtatrabaho sa GitHub. Ito rin ay isang magandang lugar para sa mga programmer na nangangailangan ng isang lugar upang mag-imbak ng dokumentasyon. Maraming tao ang gumagamit ng karaniwang Readme sa kanilang codebase para mabigyan ang user ng simpleng gabay sa kung paano, ngunit hindi ito ang tanging paraan para gumawa ng dokumentasyon sa GitHub. Sa Mga Pahina ng GitHub , nakakakuha ka ng higit pa sa pagho-host para sa mga pahina ng iyong proyekto, kasama ang dokumentasyon at mga tutorial. Makukuha mo ang kakayahang makipag-ugnayan nang direkta sa lahat ng mga repositoryo ng GitHub, na nagpapahintulot sa mga developer na i-update ang dokumentasyon sa parehong paraan kung paano nila ina-update ang kanilang code. Bukod dito, maaari mong gamitin ang Jekyll dito - tinutulungan ka nitong gawing plain text o maging ganap na mga web page ang iyong markup.

Basahin ang Docs

Gaya ng ipinahihiwatig ng pangalan, ang Read the Docs ay nagbibigay sa mga developer ng isang platform para sa pag-iimbak at pagbabasa ng dokumentasyon. Gumagana ang serbisyo tulad ng Mga Pahina ng GitHub: maaaring gumawa ng mga pagbabago ang mga programmer sa dokumentasyon mula sa kanilang mga paboritong version control system, kabilang ang Git, Bazaar, Mercurial at iba pa. Sinusuportahan din ang awtomatikong bersyon at paggawa ng pahina. Ang pinakamagandang bahagi ng Read Docs ay ang flexibility nito. Sinusuportahan nito ang mga webhook upang ma-automate mo ang karamihan sa proseso ng paggawa ng dokumento. Ito ay isang malaking time saver sa isang gawain na karamihan sa mga programmer ay walang gustong gawin. Bilang karagdagan, ang lahat ng naka-host sa platform ay magagamit sa pangkalahatang publiko sa iba't ibang mga format, kabilang ang PDF, single-page na HTML, at kahit na format ng e-book. Ang serbisyo ay tumatagal ng isang mahalagang bahagi ng nakagawiang gawain upang mapanatiling napapanahon ang dokumentasyon.

Tettra

Ang Tettra ay hindi lamang isang platform para sa pag-iimbak ng dokumentasyon ng software, ngunit isang kumpletong base ng kaalaman. Ito ay gumagana lalo na kapag ang isang proyekto ay nagsasangkot ng isang malaking grupo ng mga coder na nagtatrabaho sa iba't ibang piraso ng software. Maaaring gamitin ang Tettra upang idokumento ang mga sagot sa mga karaniwang tanong.

Apiary

Ang dahilan kung bakit lubhang kapaki-pakinabang ang Apiary para sa mga developer ay ang katotohanang ito ay gumaganap ng isang mahusay na trabaho sa pagtulong sa dokumentasyon ng API. Binibigyang-daan ng platform ang mga user na isulat ang kanilang dokumentasyon sa Markdown , kabilang ang mga kunwaring tawag sa API. Pinapayagan ka rin ng Apiary na subukan at i-prototype ang mga elemento ng API. Sa madaling salita, ito ay isang tool sa dokumentasyon at platform ng pagsubok sa isang lugar.