Егер сіздің құжаттамаңыз ашылу үшін екі рет басуды қажет етсе, құттықтаймыз - ол бұрыннан ескірген

Жылдар бойы мен әр түрлі жобалармен жұмыс істедім — үлкен, кіші, хаоты, асыра инженерлік, «уақытша», жасырын жақсы құрылған және олардың арасындағы барлық нәрселер. Дегенмен, бір заңдылық күлкілі түрде тұрақты болды: Құжаттама әрдайым жоқ, ескірген немесе Confluence-тың ұмытылған бұрышында 2019 жылғы уақыт белгісімен қорғалған. Әрбір жобада құжаттама бар деп . талап етіледі Әрбір команда оны жаңартып отырамыз деп . уәде береді Және әрбір әзірлеуші сенімді түрде: «Уайымдама, мен оны кейінірек жазамын», — дейді, бұл, бәріміз білетіндей, құжаттаманың « » дегеніне тең. the cheque is in the mail Бұл циклді өзім мойындағым келгеннен көп рет қайталанғанын көріп, мен қарапайым, бірақ өте шынайы нәрсені түсіндім: Құжаттама тек кодқа мүмкіндігінше жақын болса ғана сақталады — себебі әзірлеушілер (мені қоса алғанда) жалқау жандар. Сол себепті, тағы бір түйінді ойға келдім — ескірген құжаттаманың басты мәселесі — көптеген командалар оны негізгі әзірлеу циклінің бөлігі ретінде қарастырмайды, оны кейінге қалдырады немесе Confluence-та әлдеқашан бар екі-үш алдын ала әзірлеу спецификациясымен жұмыс істейді. Мағыналы құжаттаманы жазу үшін, алдымен бағдарламалық компонент үшін қандай құжаттама түрлері бар екенін талқылайық: Әзірлеушілер Шынымен Қолдана Алатын Кодты Құжаттау Тәсілдері Құжаттама кодқа жақын болуы керек деген ойды қабылдағаннан кейін, келесі сұрақ — оны құрылымдау керек. қалай Іс жүзінде, жақсы құжаттама бір ғана құжат емес — бұл әрқайсысы әр түрлі мақсат пен аудиторияға қызмет ететін қабаттардың кішігірім экожүйесі. Мен атап өткен жоба үшін (Java + Spring Boot-та жазылған), біз құжаттардың төрт негізгі түрін анықтадық: 1. Клиенттік спецификациялар Бұл әдетте домен сарапшысы құрастыратын дәстүрлі құжаттар. Идеалды жағдайда, олар әмбебап тілге бай және бизнес жағдайларының кодқа тәуелсіз сипаттамаларын береді — басқаша айтқанда, инженерге алдындағы мәселені шынмен түсіну үшін қажет нәрсенің бәрі. Өкінішке орай, іс жүзінде бұл құжаттар жиі Confluence-та бір жерде сақталады, жобаның басында командамен бөліседі, содан кейін олар ешқашан жаңартылмайды. Мені дұрыс түсінбеңіз: бұл құжаттар . маңызды Домен сарапшыларынан алынған білімді алу кез-келген инженерлік команда үшін басты басымдық болуы керек. Бірақ спецификациялар өзгереді, мерзімдер бәріне қысым жасайды, және бұл бастапқы құжаттар баяу, бірақ сенімді түрде ескіреді. Өзгерген талаптар, шекті жағдайлар және жоба ауысулары туралы білім кодта — немесе одан да нашар! — аға әзірлеушілердің басында сақталады. Мұны шешу үшін, біз кездейсоқ Word файлдарында немесе ұмытылуға айналған Confluence беттерінде спецификацияларды жазуды тоқтаттық және оларды мүмкіндігінше алдыңғы шепке жақын орналастырдық: код репозиторийі. Оларды репозиторий ішінде, әдетте docs/ תיבתіндt Markdown (.md) файлдары ретінде сақтай бастадық. Үлкен микросервис орталарында бұл құжаттар тіпті арнайы репозиторийді Git submodule ретінде байланыстыруды талап етуі мүмкін. Submodule жиі елеусіз қалады, бірақ олар көп репозиторий экожүйелерін ұйымдастырудың қуатты жолы. Submodule туралы қосымша оқу үшін, мен осы блог жазбасын ұсынамын — . сілтеме 2. README – Адамдар үшін Кіріспе Есік Егер клиенттік спецификациялар энциклопедия болса, README — кіріспе есік. Дегенмен, бұл бағдарламалық жобалардағы ең көп елеусіз қалдырылатын құжаттардың бірі. Айырбастау, әрбір нұсқаны басқару платформасы — GitHub, GitLab, Bitbucket — README-ді репозиторийдің негізгі бетінде автоматты түрде көрсетеді. Бұл кез-келген әзірлеуші репозиторийге кіргенде бірінші көретін нәрсе. Осыған қарамастан, README жиі таңқаларлықтай бос, аянышты түрде ескірген немесе «TODO: құжаттаманы кейін жазу» деген қасіретті сөздермен толтырылған, бұл, әрине, ешқашан болмайды. Жақсы README міндетті емес. Бұл шынымен оқылуы мүмкін жалғыз құжат, себебі оған . Және ол репозиторийдің түбірінде орналасқандықтан, әзірлеушілер кодпен жұмыс істеу кезінде оны жаңартуға бейім. Бұл ең аз кедергі жолындағы құжаттама. ешқандай басу қажет емес Жақсы жазылған README әзірлеушінің жобамен танысқан алғашқы минуттарында туындайтын ең маңызды сұрақтарға жауап беруі керек: қысқаша мақсат және контекст туралы мәлімдеме — маркетингтік ажур жоқ. Бұл қызмет/жоба/компонент не істейді? — іске қосу нұсқаулары, айнымалылар, байланысты орнату және кез-келген жобаға тән командалар. Оны жергілікті жерде қалай іске қосуға болады? — бірлік тесттері, интеграциялық тесттер, сынақ деректерін орнату және кез-келген сынаққа қатысты құралдар. Оны қалай тексеруге болады? — каталог орналасуы, негізгі модульдер және кодтың маңызды бөліктерін қайдан табуға болатыны туралы қысқаша түсіндіру. Жоба қалай құрылымдалған? — Орналастыру скрипттері, CI/CD жазбалары, қажетті рұқсаттар немесе платформа ерекшеліктері. Оны қалай орналастыруға болады? генерацияланған құжаттарға, архитектура жазбаларына, API сілтемелеріне және орталықтандырылған дизайн құжаттарына сілтемелер. Қайдан қосымша оқуға болады? — README — бұл жобаға кіру есігі. Ол күтулерді белгілейді, үйрену уақытын азайтады және әрбір инженерге — жаңа немесе тәжірибелі — анық бағыт нүктесін береді. Дұрыс сақталған кезде, ол репозиторийдегі ең құнды бір құжатқа айналады. 3. JavaDocs – Компилятор жаңартуға мәжбүрлейтін Құжаттама JavaDocs — әдетте көрінбейтін, жиі ұмытылатын, бірақ бір нәрсе бұзылған кезде өте қажет. Іс жүзінде, Java жобаларын құжаттау жиі екі экстремумға келеді: не , не , себебі «код өзін-өзі түсіндіреді». Шындық, әдеттегідей, ортада. әрбір ұсақ-түйекті шамадан тыс түсіндіру мүлдем түсініктемесіз Біздің жобамыз үшін, біз құжаттау туралы саналы шешім қабылдадық. Бұл дегеніміз: шынымен қажеттіні ғана қолдану, сонда домен терминдері бизнес спецификацияларындағы сөздермен дәл сәйкес келеді әмбебап тілді кодтың өзі көрсететін емес, дегенді түсіндіру не неліктен негізгі домен кластарын, интерфейстерін және күрделі жұмыс процестерін құжаттау әдіс атауын артық сөзбен қайталайтын түсініктемелер қабырғаларынан аулақ болу JavaDocs, дұрыс қолданылған кезде, кодты шатастырмай, ниетті нақтылайтын микродеңгейдегі құжаттама ретінде қызмет етеді. Және Confluence беттерінен айырмашылығы, JavaDocs-та артықшылық бар: Компилятор олар синхрондалмаған кезде ескертеді. Егер сіз параметрді қайта атасаңыз, бірақ JavaDoc тегін ұмытсаңыз, құрастыру сізге еске салады. Егер сіз әдісті жойсаңыз, бірақ ескі түсініктеме сілтемелерін қалдырсаңыз, IDE жаңа жылдық шырша сияқты жарықтанады. Бұл жеңіл үйкеліс — JavaDocs-тың басқа құжаттама түрлеріне қарағанда дәлдігін сақтау себебі, оларды елеусіз қалдыру жағымсыз. Барлығын орталықтандыру және «құжаттама аралдарынан» аулақ болу үшін, біз -ді де қолдандық. Doxygen Doxygen — бағдарламалық жасақтаманы әзірлеуде кеңінен қолданылатын құжаттама генераторы. Негізінен C++ қауымдастығында қолданылса да, біз оны JavaDocs-ты сәйкес, шолуға болатын анықтама — HTML парағына жинақтау үшін қолдандық. Оның JavaDoc-та жоқ бірқатар мүмкіндіктері бар, мысалы, иерархияларға арналған сызбалар және кооперативтік контекст, көп шолу парақтары және басқалары. Бұл бізге шашыраңқы IDE кеңестеріне сүйенбей, бүкіл код базасын таза, бірыңғай көруге мүмкіндік берді. 4. Таза Код – Жаңартуды Қажет Етпейтін Құжаттама Ақырында, ең бағаланбаған құжаттама түрі — әзірлеушілер оны шынымен қажет болғанша ең аз сыйлайтын: таза код. Түсініктемелер ескіреді. Спецификациялар ауытқиды. README-лер елеусіз қалады. JavaDocs ескіруі мүмкін. Бірақ жақсы жазылған код — анық, мақсатты және экспрессивті — бұл құжаттама. Аға Боб атап өткендей, «Таза код жақсы жазылған проза сияқты оқылады». Және іс жүзінде, бұл дегеніміз: мақсатын көрсететін атаулары бар кластар мен әдістер бір нәрсе істейтін және оны жақсы істейтін функциялар бүкіл бойында тұрақты қолданылатын домен терминологиясы тек өзі үшін ақылдылық жоқ жанама әсерлер ішінде жасырылған «таңқаларлық әрекеттер» жоқ PhD қажет ететін негізсіз терең абстракциялар жоқ Таза код — бұл рефакторингтерді, спринттерді, персоналдың ауысуын және ұйымдастырушылық хаосты жеңетініне кепілдік беретін жалғыз артефакт. Ол жүйенің мінез-құлқымен әрдайым синхрондалады, себебі — ол жүйенің . мінез-құлқы Біздің уақытымызда қарапайым ереже пайда болды: Егер сізге әдісті түсіндіру үшін бір абзац түсініктеме қажет болса, нағыз мәселе — әдіс. Код экспрессивті болған кезде, басқа бәрі жеңілдейді → JavaDocs жеңілдейді және шоғырланады → README қысқарады, себебі үйрену оңай болады → спецификациялар анықтай түседі, себебі домен моделі бизнес лексикасын бейнелейді. Таза код құжаттама қажеттілігін жоймайды; ол оны . бекітеді Ол басқа құжаттама түрлерінің — спецификациялар, README-лер, JavaDocs — анық емес іске асыруды өтеудің орнына, шындықты растауын қамтамасыз етеді. Соңында, таза код — бұл ешқандай техникалық қызмет көрсетуді, CI интеграциясын және ешқандай құралдарды талап етпейтін құжаттама. Бұл жүйенің шынымен не істейтінін ең адал, сенімді түсіндірмесі. Бәрін Біріктіру — Тірі Құжаттама Конвейері Құжаттаманы қалай жазғанымызды нақтылағаннан кейін, соңғы қадам — оның тек жасалғанына ғана емес, үздіксіз жеткізіліп, әрдайым қолжетімді болуын қамтамасыз ету болды. Сол үшін біз спецификацияларымызды, README файлдарын және JavaDocs-ты бірыңғай, біріккен айналдыратын құжаттама конвейерін құрдық. тірі құжаттама порталына Біз құжаттарымызды кодымызға мүмкіндігінше жақын болғанын қалағандықтан, біз арқылы бәрін орналастыруға шешім қабылдадық, бұл код базасына тікелей байланысты, оңай, нұсқаны басқаратын хостинг шешімін берді. Github Pages GitHub-қа тән емес (мысалы, GitLab-та GitLab pages де бар) — бұл танымал нұсқаны басқару жүйелерінің тағы бір тамаша мүмкіндігі, мен оны қосымша оқуға ұсынамын — . GitHub Pages сілтеме Барлығын үйлесімді парақтар жиынтығына жинақтау үшін, біз -ті қолдандық. Sphinx Sphinx — Python-да жазылған қуатты құжаттама генераторы. Ол reStructuredText немесе Markdown-да жазылған бастапқы файлдарды алады және оларды HTML, PDF және ePub сияқты әр түрлі шығару форматтарына аударады. Sphinx құрылымды, навигацияны және тақырыптарды басқарды. Doxygen бізге код базасынан тікелей толық шолуға болатын API анықтамасын беріп, плагині арқылы автогенерацияланған JavaDocs-ты Sphinx-ке берді. Сол уақытта, негізгі README репозиторийді зерттеуші әзірлеушілерге тікелей кіру нүктесі ретінде қызмет етті, генерацияланған құжаттама сайтына үздіксіз сілтеме жасады. Breathe Әрбір main-ге біріктіру құжаттарды қайта құрастыратын CI жұмысын іске қосты, бұл порталдың соңғы код өзгерістерін, API жаңартуларын және дизайн шешімдерін көрсететініне кепілдік берді. Ештеңе оқшауланбады. Ештеңе қолмен синхрондауды талап етпеді. Және ең бастысы — ештеңе бір басудан артық болмады. Бұл біздің құжаттамамызды статист артефакттан әзірлеушілер шынымен қолданатын, үздіксіз жаңартылатын экожүйеге айналдырды, себебі ол олардың күнделікті жұмыс процестеріне тікелей енгізілген және кодпен қатар болған. Қорытынды — Құжаттама Біздің Жауапкершілігіміз, Біздің Жүгіміз Емес Күндізгі уақыттың соңында, құжаттама жазу міндетті емес. Бұл біздің инженер-мамандар ретіндегі жұмысымыздың бөлігі. Болашақ командаластар оған сенеді. Үйрену оған сенеді. Техникалық қызмет көрсету, сенімділік және тіпті архитектуралық анықтық оған сенеді. Бірақ бұл жауапкершілікті қабылдау құжаттама ауыр болуы керек дегенді білдірмейді. Құжаттаманы кодқа жақын ұстап, мүмкіндігінше автоматтандыруды жүзеге асыру және Markdown, JavaDocs, Doxygen және Sphinx сияқты ақылды құралдарға сүйену арқылы, біз құжаттама күш-жігерін жоятын үйкелісті жоямыз. Біз әдеттегідей ауыр жұмыс сияқты сезілетін нәрсені күнделікті әзірлеудің табиғи кеңейтіміне айналдырамыз. Және біз оны таза кодпен, жақсы README-лермен және доменге бай спецификациялармен жұптастырғанда, бүкіл экожүйе өзін-өзі ұстайтын болады. Құжаттама мінсіз болуы міндетті емес — ол тек қолжетімді, дәл және тірі болуы керек. Біз әзірлеушілерді код жазғандай оңай құжаттарды жаңартуға ынталандыратын жүйелерді құрғанда, бәрі ұтысқа ие болады: команда, өнім және ең бастысы, алты айдан кейін жобаны мұраға алатын бейшара жан. Жақсы құжаттама бізді аз жалқау етпейді. Ол жай ғана жалқаулықты тамаша бағдарламалық жасақтама құрумен үйлесімді етеді.