JavaRush /Java блогы /Random-KK /Кофе-брейк №20. Бұрынғы код дегеніміз не және онымен қала...

Кофе-брейк №20. Бұрынғы код дегеніміз не және онымен қалай жұмыс істеу керек. Техникалық құжаттаманы жазуды жеңілдететін құралдар

Топта жарияланған

Бұрынғы code дегеніміз не және онымен қалай жұмыс істеу керек

Дереккөз: Dou Ерте және кеш бағдарламашы бұрынғы codeқа тап болуы мүмкін. Осы таныстықтың салдарын жеңілдету үшін мен өз тәжірибемнен бірнеше практикалық кеңестер мен мысалдарды таңдадым, атап айтқанда, бұрынғы Java жүйесімен жұмыс істеу. Кофе-брейк №20.  Бұрынғы code дегеніміз не және онымен қалай жұмыс істеу керек.  Техникалық құжаттаманы жазуды жеңілдететін құралдар – 1

Бұрынғы мүмкіндіктер

Мұра - бұл басқа біреудің codeы, ол жиі қорқынышты болғандықтан, онымен қалай жұмыс істеу керектігі түсініксіз. Ал егер сізге ескі жүйемен жұмыс істеу керек болса, ескі codeқа қоса, сіз де тап боласыз:
  • ескірген технологиямен;
  • гетерогенді архитектура;
  • құжаттаманың болмауы немесе тіпті толық болмауы.
Шын мәнінде, бұрынғы code соншалықты қорқынышты емес, сондықтан: егер жүйе осы он жыл бойы өмір сүріп, әлі де жұмыс істеп тұрса, оның біраз пайдасы бар. Мүмкін бұл жақсы ақша табады (соңғы стартаптан айырмашылығы). Сонымен қатар, бұл code өндірісте ұзақ уақыт бойы өмір сүре алатын болса, салыстырмалы түрде сенімді. Сондықтан оған өзгертулер сақтықпен жасалуы керек. Ең алдымен, сіз екі нәрсені түсінуіңіз керек:
  1. Біз миллиондаған табыс әкелетін немесе күніне мыңдаған адамдар кіретін жүйені құрметтемей алмаймыз. Қаншалықты нашар жазылғанымен, бұл жиіркенішті code өндіріске дейін аман қалды және тәулік бойы жұмыс істейді.

  2. Бұл жүйе нақты ақша әкелетіндіктен, онымен жұмыс істеу үлкен жауапкершілікті талап етеді. Бұл стартап емес, пайдаланушылар ертең жұмыс істейтін нәрсе. Бұл сондай-ақ қатенің өте жоғары құнын білдіреді және бұл жерде мәселе клиенттің талаптарында емес, нақты жағдайдағы жағдай.

Кері инженерия

Бұрынғы codeпен сәтті жұмыс істеу үшін сізге кері инженерия әдістерін қолдану керек. Алдымен оның қалай жұмыс істейтінін түсіну үшін codeты мұқият оқып шығу керек. Бұл міндетті, өйткені бізде құжаттама болмайды. Егер біз автордың ой-пікірін түсінбесек, күтпеген салдары бар өзгерістер жасаймыз. Бұдан өзіңізді қорғау үшін сізге көрші codeты тереңдету керек. Сонымен қатар, тек кеңдікте ғана емес, тереңдікте де қозғалады. Қатемен шақырылатын әдіс қайда? Оны шақыратын code қайдан келеді? Бұрынғы жобада "шақыру иерархиясы" және "түр иерархиясы" кез келген нәрсеге қарағанда жиі пайдаланылады. Түзеткішпен көп уақыт жұмсауға тура келеді: біріншіден, қателерді табу, екіншіден, бәрі қалай жұмыс істейтінін түсіну. Құжаттамаға келетін болсақ, өнеркәсіптік археологияға жүгіну жаман идея болмас еді. Бір жерде ескі құжаттаманы қазып алу және мұраланған codeтың қалай жазылғанын есте сақтайтындармен сөйлесу өте пайдалы болуы мүмкін. Осы әдістерді қолдана отырып, сіз ерте ме, кеш пе codeты азды-көпті түсіне бастайсыз. Бірақ сіздің күш-жігеріңіз текке кетпеу үшін сіз зерттеу нәтижелерін дереу құжаттауыңыз керек. Ол үшін блок-схема немесе реттілік схемасын салуды ұсынамын. Әрине, сіз жалқау боласыз, бірақ мұны міндетті түрде жасауыңыз керек, әйтпесе алты айдан кейін құжатсыз сіз бұл codeты бірінші рет сияқты қазып аласыз.

Кодты қайта жазбаңыз

Әзірлеу процесіндегі ең маңызды нәрсе - өзіңізді уақытында жеңу және бүкіл codeты нөлден қайта жазуға тырыспау. Бұл үшін қанша адам-жыл қажет болатынын есептеңіз. Клиент бұрыннан жұмыс істеп тұрған нәрсені қайта жасауға сонша көп ақша жұмсағысы келетіні екіталай. Бұл жалпы жүйеге ғана емес, оның кез келген бөлігіне де қатысты. Әрине, олар сізге бәрін анықтауға бір апта, ал бірдеңені түзетуге тағы бір апта беруі мүмкін. Бірақ олар сізге жүйенің бір бөлігін қайтадан жазуға екі ай уақыт беруі екіталай. Оның орнына, жаңа функцияны codeтың қалған бөлігімен бірдей стильде орындаңыз. Басқаша айтқанда, егер code ескі болса, сіз жаңа әдемі технологияларды қолдануға азғырылмауыңыз керек: мұндай codeты оқу өте қиын болады. Мысалы, сіз бізде болған жағдайға тап болуыңыз мүмкін: жүйенің бір бөлігі Spring MVC-де жазылған, ал бөлігі жалаң сервлеттерде жазылған. Ал егер сервлеттерде жазылған бөлікке тағы бір нәрсе қосу керек болса, біз оны дәл солай - сервлеттерде қосамыз.

Іскерлік мүдделерді құрметтеңіз

Кез келген міндеттер, ең алдымен, бизнес үшін құндылығымен анықталатынын есте ұстаған жөн. Егер сіз тұтынушыға бизнес тұрғысынан белгілі бір өзгерістердің қажеттілігін дәлелдемесеңіз, бұл өзгерістер болмайды. Ал тұтынушыны сендіру үшін оның орнында тұрып, оның мүдделерін түсінуге тырысу керек. Атап айтқанда, егер сіз codeты оқу қиын болғандықтан ғана рефакторлауды қаласаңыз, сізге оны жасауға рұқсат берілмейді және онымен өмір сүруге тура келеді. Егер сіз шынымен шыдай алмасаңыз, жұмысты іскерлік билеттерге тарата отырып, codeты тыныш және біртіндеп қайта ұйымдастыра аласыз. Немесе тұтынушыны бұл, мысалы, қателерді табу үшін қажетті уақытты қысқартатынына және ақыр соңында шығындарды азайтатынына сендіріңіз.

Сынақ

Кез келген жобада тестілеу қажет екені анық. Бірақ ескі жүйелермен жұмыс істегенде, тестілеуге ерекше назар аудару керек, өйткені енгізілген өзгерістердің әсері әрқашан болжалмайды. Сізге кем дегенде әзірлеушілер сияқты көптеген тестерлер қажет болады, әйтпесе сіз автоматтандыруда керемет жақсы болуыңыз керек. Біздің жобада тестілеу келесі кезеңдерден тұрды:
  1. Тексеру, мүмкіндіктің іске асырылған функционалдығы бөлек тармақта тексерілген кезде.
  2. Барлық мүмкіндіктер біріктірілген шығарылым тармағы тексерілгенде тұрақтандыру.
  3. Сертификаттау, сол нәрсе аппараттық құрал сипаттамалары мен конфигурациясы бойынша өндіріске мүмкіндігінше жақын сертификаттау ортасында сәл басқа сынақ жағдайларында қайта іске қосылғанда.
Осы үш кезеңнен өткеннен кейін ғана біз шығарылым жасай аламыз. Біреу сертификаттауды қосымша кезең деп ойлайтын шығар, өйткені бәрі тұрақтандыру кезеңінде нақтыланған, бірақ біздің тәжірибеміз бұлай емес екенін көрсетеді: кейде басқа машинада екінші раундқа өткізілетін регрессия тесті кезінде қандай да бір нәрсе. ол шығады.

DevOps-ті ресімдеу және шығару

Шығару proceduresасы, мысалы, келесідей болуы мүмкін. Әзірлеу аяқталып, екі немесе үш сынақ кезеңі аяқталғанда, біз DevOps командасына күтілетін шығарылым уақытынан 36 сағат бұрын электрондық хат жазамыз. Осыдан кейін біз devops командасын шақырамыз және орталардағы барлық өзгерістерді талқылаймыз (біз оларға дерекқордағы және конфигурациядағы барлық өзгерістер туралы хабарлаймыз). Әрбір өзгерту үшін бізде құжат бар (Джирада билет). Содан кейін шығарылым кезінде бұған қатысқандардың барлығы жиналып, барлығы қазір не істеп жатқандарын айтады: «Біз дерекқорды жүктеп салдық», «Біз осындай және осындай serverлерді қайта іске қостық», «Біз өндірістік ортада регрессия сынақтарын жүргізуге бардық. » Егер бірдеңе дұрыс болмаса, бастапқы шығарылым құжатында дәл сипатталған шығарылымды кері қайтару proceduresасы іске қосылады - мұндай құжатсыз біз бір нәрсені ұмытып кетеміз немесе шатасамыз.

Код сапасын бақылау

Ақырында, codeты қарап шығу - бұл қандай да бір себептермен барлық жобаларда қолданыла бермейтін тәжірибе. Әрбір code бөлігін бірнеше адам қарастырса, бұл өте жақсы. Тіпті өте күшті командада да кейбір қателер codeты қарап шығу процесінде әрқашан ашылады және егер оған бірнеше адам қараса, анықталған қателер саны артады. Оның үстіне кейде үшінші немесе төртінші рецензент ең сорақысын табады.

Техникалық құжаттаманы жазуды жеңілдететін құралдар

Дереккөз: Dzone Көптеген бағдарламашылар техникалық құжаттама жазуды ұнатпайды. Психология сарапшысы Джеральд Вайнберг тіпті құжаттаманы «бағдарламалаудың касторлық майы» деп атады: әзірлеушілер оны оқығанды ​​жақсы көреді, бірақ оны өздері жазуды жек көреді. Кофе-брейк №20.  Бұрынғы code дегеніміз не және онымен қалай жұмыс істеу керек.  Техникалық құжаттаманы жазуды жеңілдететін құралдар – 2Нұсқаулықтың немесе бос жол картасының болмауы бағдарламалық құралдың әртүрлі бөліктері қалай жұмыс істейтіні туралы ақпараттың болмауына әкеледі. Бұл, сайып келгенде, codeтың соңғы пайдаланушыларының тәжірибесін нашарлатады, себебі құжаттама болмаған жағдайда, олар өнімнің дәлдігі мен пайдалылығына сене алмайды. Бағдарламашыларға құжаттама жазу әдетін қалыптастыруды жеңілдету үшін мен барлығына дерлік қол жетімді төрт тамаша құралға назар аударуды ұсынамын.

GitHub беттері

Бүгінгі күні GitHub-те жұмыс істеу тәжірибесі жоқ бірде-бір әзірлеуші ​​жоқ шығар. Бұл сонымен қатар құжаттаманы сақтауды қажет ететін бағдарламашылар үшін тамаша орын. Көптеген адамдар пайдаланушыға қарапайым нұсқаулықты ұсыну үшін code базасында стандартты Readme пайдаланады, бірақ бұл GitHub-та құжаттама жасаудың жалғыз жолы емес. GitHub беттері арқылы сіз құжаттама мен оқулықтарды қоса алғанда, жобаның беттеріне арналған хостингтен көбірек аласыз. Сіз барлық GitHub репозиторийлерімен тікелей өзара әрекеттесу мүмкіндігіне ие боласыз, бұл әзірлеушілерге құжаттаманы codeты жаңартқандай жаңартуға мүмкіндік береді. Сонымен қатар, сіз Jekyll қолданбасын осында пайдалана аласыз - бұл сіздің түзетулеріңізді кәдімгі мәтінге немесе толыққанды веб-беттерге айналдыруға көмектеседі.

Құжаттарды оқыңыз

Аты айтып тұрғандай, Read the Docs әзірлеушілерге құжаттарды сақтауға және оқуға арналған платформаны ұсынады. Бұл қызмет GitHub Pages сияқты жұмыс істейді: бағдарламашылар Git, Bazaar, Mercurial және т.б. қоса, таңдаулы нұсқаларды басқару жүйелерінен құжаттамаға өзгертулер енгізе алады. Автоматты нұсқаға және бет жасауға да қолдау көрсетіледі. Read Docs бағдарламасының ең жақсы бөлігі оның икемділігі болып табылады. Құжатты жасау процесінің көп бөлігін автоматтандыру үшін ол веб-хуктарды қолдайды. Бұл көптеген бағдарламашылар ештеңе істегісі келмейтін тапсырманы орындау үшін үлкен уақытты үнемдеу. Сонымен қатар, платформада орналастырылған барлық нәрсе PDF, бір беттік HTML және тіпті электрондық кітап пішімін қоса алғанда, әртүрлі пішімдерде көпшілікке қол жетімді. Қызмет құжаттаманы жаңарту бойынша күнделікті жұмыстың маңызды бөлігін алады.

Теттра

Tettra - бұл бағдарламалық құжаттаманы сақтауға арналған платформа ғана емес, толық білім базасы. Бұл жоба бағдарламалық жасақтаманың әртүрлі бөліктерінде жұмыс істейтін codeерлердің үлкен тобын қамтитын болса, әсіресе жақсы жұмыс істейді. Tettra жалпы сұрақтарға жауаптарды құжаттау үшін пайдаланылуы мүмкін.

Омартаны

Apiary-ті әзірлеушілер үшін соншалықты пайдалы ететін нәрсе - бұл API құжаттамасына көмектесуде тамаша жұмыс. Платформа пайдаланушыларға өздерінің құжаттамасын Markdown жүйесінде, соның ішінде жалған API қоңырауларын жазуға мүмкіндік береді . Apiary сонымен қатар API элементтерін сынауға және прототипін жасауға мүмкіндік береді. Басқаша айтқанда, бұл бір жерде құжаттама құралы және тестілеу платформасы.
Пікірлер
TO VIEW ALL COMMENTS OR TO MAKE A COMMENT,
GO TO FULL VERSION