Kofe arakesmesi # 20 Miras kody näme we onuň bilen nädip işlemeli. Tehniki resminamalary ýazmagy aňsatlaşdyrýan gurallar

Miras kody näme we onuň bilen nädip işlemeli

Çeşme: Dou Iru-giç programmist miras kody bilen ýüzbe-ýüz bolmaly bolar. Bu tanyşlygyň netijelerini ýeňilleşdirmek üçin, öz tejribämden, esasanam, miras galan Java ulgamy bilen işleýän käbir amaly maslahatlary we mysallary saýladym.

Miras aýratynlyklary

Miras başga biriniň kody bolup, köplenç şeýle gorkunç bolup, onuň bilen nädip işlemelidigi belli däl. Miras ulgamy bilen işlemeli bolsaňyz, köne koddan başga-da duşarsyňyz:

• köne tehnologiýa bilen;
• birmeňzeş arhitektura;
• resminamalaryň ýoklugy ýa-da hatda doly ýoklugy.

Aslynda, miras kody beýle gorkunç däl we munuň sebäbi: ulgam şu on ýyl ýaşap, henizem işleýän bolsa, onda birneme peýdasy bar. Belki gowy pul gazanar (soňky başlangyçdan tapawutlylykda). Mundan başga-da, bu kod uzak wagtlap önümçilikde ýaşap bilse, has ygtybarlydyr. Şonuň üçin oňa üýtgetmeler seresaplylyk bilen edilmeli. Ilki bilen iki zada düşünmeli:

1. Günde millionlarça adam gazanýan ýa-da günde müňlerçe adamyň elýeterli ulgamyna hormat goýup bilmeris. Näçe erbet ýazylsa-da, bu ýigrenji kod önümçilige çenli dowam edip, gije-gündiziň dowamynda işleýär.

2. Bu ulgam hakyky pul getirýändigi sebäpli, onuň bilen işlemek uly jogapkärçilik bilen gelýär. Bu başlangyç däl, ulanyjylaryň ertir işlejek zady. Bu, şeýle hem, ýalňyşlygyň gaty ýokary bahasyny göz öňünde tutýar we bu ýerdäki mesele müşderiniň talaplarynda däl-de, hakyky işde.

Ters in engineeringenerlik

Miras kody bilen üstünlikli işlemek üçin ters in engineeringenerçilik usullaryny ulanmaly bolarsyňyz. Ilki bilen, işleýşine düşünmek üçin kody üns bilen okamaly. Bu hökmany, sebäbi resminamalarymyz bolmaz. Awtoryň pikir otlusyna düşünmesek, garaşylmadyk netijeler bilen üýtgeşmeler girizeris. Özüňizi bu zatlardan goramak üçin goňşy kody öwrenmeli. Şol bir wagtyň özünde diňe bir giňlikde däl, eýsem çuňlukda hem hereket ediň. Erroralňyşlyk bilen usul nirede diýilýär? Çagyrýan kod nireden gelýär? Miras taslamasynda "jaň iýerarhiýasy" we "görnüşli iýerarhiýa" hemme zatdan has ýygy ulanylýar. Düzediji bilen köp wagt geçirmeli bolarsyňyz: birinjiden, ýalňyşlyklary tapmak, ikinjiden, hemme zadyň nähili işleýändigine düşünmek. Resminamalar barada aýdylanda bolsa, senagat arheologiýasyna ýüz tutmak erbet pikir bolmaz. Bir ýerde köne resminamalary gazyp, miras galan koduňyzyň nähili ýazylandygyny ýada salýanlar bilen gürleşmek gaty peýdaly bolup biler. Bu usullary ulanyp, iru-giç koda has az düşünip başlarsyňyz. Emma tagallalaryňyzyň puja çykmagynyň öňüni almak üçin gözlegleriň netijelerini derrew resminama etmeli. Munuň üçin blok diagrammalaryny ýa-da yzygiderlilik diagrammalaryny çyzmagy maslahat berýärin. Elbetde, ýalta bolarsyňyz, ýöne muny hökman etmeli, ýogsam alty aýdan resminamasyz bu kody ilkinji gezek bolşy ýaly gazarsyňyz.

Kody täzeden ýazmaň

Ösüş prosesinde iň möhüm zat, özüňizi wagtynda urmak we ähli kody noldan ýazmaga synanyşmazlykdyr. Munuň üçin näçe ýyl gerek boljakdygyny çaklaň. Müşderiniň eýýäm işleýän bir zadyny täzeden işlemek üçin gaty köp pul sarp etmek islemegi gaty ähtimal. Bu diňe bir tutuş ulgam üçin däl, eýsem onuň islendik bölegine-de degişlidir. Elbetde, hemme zady anyklamak üçin size bir hepde, bir zady düzetmek üçin ýene bir hepde wagt berip bilerler. Emma ulgamyň bir bölegini täzeden ýazmak üçin size iki aý wagt bermegi gaty ähtimal. Munuň ýerine, täze funksiýany koduň galan bölekleri ýaly stilde durmuşa geçiriň. Başga bir söz bilen aýdylanda, kod köne bolsa, täze owadan tehnologiýalary ulanmaga synanyşmaly dälsiňiz: şunuň ýaly kody okamak gaty kyn bolar. Mysal üçin, biziň ýaly ýagdaýa duçar bolup bilersiňiz: ulgamyň bir bölegi Bahar MVC-de, bir bölegi ýalaňaç serwetlerde ýazylýar. Serwetlerde ýazylan bir bölekde başga bir zat goşmaly bolsa, biz ony edil şonuň ýaly - servletlerde goşarys.

Işewürlik gyzyklanmalaryna hormat goýuň

Islendik meseläniň, ilkinji nobatda, işiň gymmaty bilen kesgitlenýändigini ýatdan çykarmaly däldir. Müşderä iş nukdaýnazaryndan käbir üýtgeşmeleriň zerurdygyny subut etmeseňiz, bu üýtgeşmeler bolmaz. Müşderini ynandyrmak üçin onuň ýerinde durmaga we onuň gyzyklanmalaryna düşünmäge synanyşmaly. Hususan-da, diňe kod okamak kyn bolany üçin refaktor etmek isleseňiz, size rugsat berilmez we siz onuň bilen ýaşamaly bolarsyňyz. Eger hakykatdanam çydap bilmeýän bolsaňyz, işi iş biletlerine ýaýradyp, ýuwaş-ýuwaşdan kody üýtgedip bilersiňiz. Ora-da müşderini, meselem, ýalňyşlyklary tapmak üçin zerur wagty azaldar we netijede çykdajylary azaldar diýip ynandyryň.

Synag

Synagyň islendik taslamada zerurdygy düşnüklidir. Emma miras ulgamlary bilen işleýän wagtyňyz, synaglara aýratyn üns berilmelidir, sebäbi edilen üýtgeşmeleriň täsiri hemişe öňünden aýdyp bolmaýar. Iň bärkisi işläp düzüjiler ýaly köp synagçy gerek bolar, ýogsam awtomatlaşdyrmaga ajaýyp ökde bolmaly. Taslamamyzda synag aşakdaky tapgyrlardan ybaratdy:

1. Aýratynlygyň ýerine ýetirilen funksiýasy aýratyn şahada barlananda barlamak.
2. Featureshli aýratynlyklaryň birleşdirilen goýberiş şahasy barlananda durnuklaşdyrmak.
3. Şahadatnama, enjamyň aýratynlyklary we konfigurasiýasy taýdan önümçilige mümkin boldugyça ýakyn bolan sertifikat gurşawynda birneme üýtgeşik synag ýagdaýlarynda gaýtadan işledilende.

Diňe şu üç tapgyryň hemmesinden geçenimizden soň çykaryp bileris. Kimdir biri, sertifikasiýa goşmaça tapgyrdyr öýdýär, sebäbi durnuklaşdyryş tapgyrynda hemme zat eýýäm aýdyňlaşdyryldy, ýöne biziň tejribämiz munuň beýle däldigini görkezýär: käwagt başga bir enjamda ikinji tapgyra çykýan regress synagy wagtynda, nämüçindir bir zat çykar.

“DevOps” -y resmileşdiriň

Goýbermek prosedurasy, meselem, aşakdaky ýaly bolup biler. Ösüş tamamlanandan we iki ýa-da üç synag tapgyry tamamlanandan soň, garaşylýan goýberiliş wagtyndan 36 sagat öň DevOps toparyna e-poçta ýazýarys. Ondan soň, devops toparyna jaň edýäris we daşky gurşawdaky ähli üýtgeşmeleri ara alyp maslahatlaşýarys (maglumat bazasyndaky we konfigurasiýadaky ähli üýtgeşmeler hakda olara habar berýäris). Her üýtgeşme üçin resminamamyz bar (Jirada bilet). Soňra, goýberilende, bu işe gatnaşanlaryň hemmesi bir ýere jemlenýär we her kim häzir näme edýändigini aýdýar: "Maglumat bazasyny ýükledik", "Şeýle we şeýle serwerleri täzeden açdyk", "Önümçilik gurşawynda regress synaglaryny geçirmäge gitdik. " Bir zat ýalňyşsa, asyl goýberiş resminamasynda takyk görkezilen goýberilişiň yzyna gaýtarylmagy prosedurasy başlaýar - beýle resminama bolmasa hökman bir zady ýatdan çykararys ýa-da bulaşarys.

Dolandyryş kodunyň hili

Netijede, kod gözden geçirmek, käbir sebäplere görä ähli taslamalarda ulanylmaýar. Her kod bölegi birden köp adam tarapyndan gözden geçirilse gaty gowy. Hatda gaty güýçli toparda-da kod gözden geçirilişinde käbir kemçilikler elmydama ýüze çykarylýar we birnäçe adam oňa seretse, kesgitlenen näsazlyklaryň sany köpelýär. Mundan başga-da, käwagt üçünji ýa-da dördünji synçy iň erbet zady tapýar.

Tehniki resminamalary ýazmagy aňsatlaşdyrýan gurallar

Çeşme: Dzone Programmistleriň köpüsi tehniki resminamalary ýazmagy halamaýarlar. Psihologiýa hünärmeni Gerald Weinberg hatda resminamalary “programmirlemegiň kastor ýagy” diýip atlandyrdy: döredijiler ony okamagy halaýarlar, ýöne ýazmagy ýigrenýärler. Guidanceolbaşçylygyň ýoklugy ýa-da boş ýol kartasy, programma üpjünçiliginiň dürli bölekleriniň işleýşi barada maglumatyň ýoklugyna sebäp bolýar. Netijede, koduň soňky ulanyjylary üçin tejribe hasam erbetleşýär, sebäbi resminamalar ýok halatynda önümiň takyklygyna we peýdalylygyna bil baglap bilmeýärler. Programmistlere resminama ýazmak endigini emele getirmegi aňsatlaşdyrmak üçin, häzirki wagtda hemmeler üçin diýen ýaly dört sany ajaýyp gurallara üns bermegi maslahat berýärin.

GitHub sahypalary

Häzirki wagtda GitHub-da işlemek tejribesi bolmadyk ýekeje-de dörediji ýok bolsa gerek. Şeýle hem resminamalary saklamak üçin bir ýere mätäç programmistler üçin ajaýyp ýer. Köp adam ulanyjylara ýönekeý ýol görkezmegi üpjün etmek üçin kod bazasynda adaty Readme ulanýarlar, ýöne bu GitHub-da resminamalary döretmegiň ýeke-täk usuly däl. GitHub sahypalary bilen , resminamalaryňyzy we okuw gollanmalaryňyzy goşmak bilen, taslamaňyzyň sahypalaryny ýerleşdirmek bilen çäklenmeýär. Githli GitHub ammarlary bilen gönüden-göni aragatnaşyk saklamak ukybyna eýe bolup, döredijilere resminamalary kodlaryny täzeleýşi ýaly täzelemäge mümkinçilik berýär. Mundan başga-da, “Jekyll” -y şu ýerde ulanyp bilersiňiz - bellikleriňizi ýönekeý tekste ýa-da doly hukukly web sahypalaryna öwürmäge kömek edýär.

Resminamalary okaň

Adyndan görnüşi ýaly, “Docs Read” döredijilere resminamalary saklamak we okamak üçin platforma hödürleýär. Hyzmat GitHub sahypalary ýaly köp işleýär: programmistler Git, Bazar, Mercurial we başgalar ýaly halaýan wersiýa dolandyryş ulgamlaryndan resminamalara üýtgeşmeler girizip bilerler. Awtomatiki wersiýa we sahypa döretmek hem goldanýar. “Docs Read” -iň iň gowy tarapy onuň çeýeligi. Resminamalary döretmek prosesiniň köpüsini awtomatlaşdyrmak üçin web sahypalaryny goldaýar. Bu, programmistleriň köpüsiniň hiç zat islemeýän meselesinde gaty köp wagt tygşytlaýjydyr. Mundan başga-da, platformada ýerleşdirilen zatlaryň hemmesi köpçülige dürli formatda, şol sanda PDF, bir sahypalyk HTML we hatda elektron kitap görnüşinde hem elýeterlidir. Hyzmat resminamalary täzeläp durmak üçin gündelik işleriň ep-esli bölegini alýar.

Tettra

Tettra diňe bir programma üpjünçiliginiň resminamalaryny saklamak üçin platforma däl, eýsem doly bilim bazasydyr. Taslama dürli programma üpjünçiliginiň üstünde işleýän kodlaýjylaryň uly toparyny öz içine alanda esasanam gowy işleýär. Tettra umumy soraglara jogaplary resminamalaşdyrmak üçin ulanylyp bilner.

Gämi duralgasy

“Apiary” -ny döredijiler üçin şeýle peýdaly edýän zat , onuň API resminamalaryna kömek etmekde ajaýyp iş edýändigi. Platforma ulanyjylara resminamalaryny Markdown -da , şol sanda mock API jaňlaryny ýazmaga mümkinçilik berýär. “Apiary” size API elementlerini barlamaga we prototip etmäge mümkinçilik berýär. Başgaça aýdylanda, bu bir ýerde resminama guraly we synag platformasydyr.