Uzun illərdir, böyük, kiçik, chaotic, overengineered, “sürücülükli” və hər şey arasında işləmişəm. The documentation is always missing, outdated, or buried in some forgotten corner of Confluence guarded by a 2019 timestamp. Hər bir projekt dokumentasiya etmək üçün. Tədbirlər Hər komanda Bunu güncelleməyə çalışacaqlar. Sözlər Hər bir istehsalçı güman edir ki, “qorxmayın, sonra yazacağam”, bu, hamımız bildiyimiz kimi, deyilənə eşidəndir. “Şeklər postda var” Bu döngüyü qəbul etmək istədiyimdən daha çox tekrar etdiyini izlədikdən sonra, basit, lakin brutal bir həqiqəti anladım: 
 
 “Dokumentasiya mümkün olduğunca kodla yaxın yaşayırsa, ancaq yaşayır – çünki geliştiricilər (məndən ibarətdir) lənətli yaratıqlardır. Documentation only survives if it lives as close to the code as possible—because developers (myself included) are lazy creatures. Bu səbəbdən, başqa bir anlayış gəldi - əvvəllərki dokumentasiya ilə bağlı böyük problem, çoğu komanda bunu ana geliştirmə ciklusunun bir parçası olaraq düşünmür, sonra üçün qoyub ya da Confluence-də bir yerdə olan bir neçə pre-dev spesifikasiyası ilə bağlıdır. Yazmaq üçün anlamlı dokumentasiya, öncə bir proqram komponenti üçün hansı tipin dokumentasiyası var: Ways to Document Code (That Developers Might Actually Use) “Dokument kodunun yolları” (Bu, geliştiricilər tərəfindən istifadə edilə bilər) Bir neçə ildir ki, bu problemin nəticəsi ilə bağlı sorğu-sual olunmalıdır. Bunu strukturlaşdırmaq lazımdır. necə Praktikda, yaxşı dokumentasiya yalnız bir artefakt deyil, hər biri başqa bir nişanə və auditoriyaya xidmət edən, minicik layerlərin ekosistemidir. “Java” və “Spring Boot” ilə yazılan bu proqnozda, dörd əsas dokument tipini tanımışıq: 1. Client Specs İdeal olaraq, onlar hər yerdəki dildədir və iş məsələlərinin kod-agnostiki tariflərini verirlər - başqa bir deyişlə, bir inžinərin problemini həqiqətən anlamaq üçün ehtiyacı olan hər şey. Şübhəsiz ki, həqiqətdə, bu dokumentlar sıklıqla Confluence-də bir yerdə saxlanır, bir projektin başlanğıcında komandayla paylaşılır və sonra heç vaxt yeniləmir. Məni yanlış anlamayın: Bu kitablar Ötən İŞİD Amma spesifiklər dəyişir, müddətlər hər kəsə ağırlıq verir və o orijinal dokumentlar yavaş-yavaş, lakin əlbəttə, ömrünün sonunadək bitməlidir. VVD - Hollandiyada futbolçu bu adla tanımır, orada VVD daha çox mərkəz-sağı təmsilən edən siyasi partiyanın adının qısaltması kimi bilinir - artıq sorğu-suala ehtiyacı olmayan ulduzdu. Bu problemlə başa düşmək üçün, unutulmaq üçün hazırlanmış random Word dosyalarında və ya Confluence saytlarında spesifikasiyaları yazmaqdan vaz keçirdik və onları mümkün olduğunca ön sıraya yaxınlaşdırdıq: the code repository. Biz onları repo içində Markdown (.md) dosyaları kimi saxlamaya başladıq, genellikle bir docs / folderda. Böyük mikroservisi ortamlarında, bu dokumentlar Git submodulları kimi bağlanan bir dedikasiyalı repositoryunu da xahiş edə bilərlər, lakin onlar multi-repo ekosistemləri organizasiya etmək üçün güclü bir yoldur. Daha çox məlumat üçün, bu blogun nəticələri haqqında məlumat verəcəyəm. . Linklər 2. README – The Front Door for Humans Əgər müştərinin spesifikasiyası enciklopediyadırsa, README ilk qapıdır. İronik olaraq, GitHub, GitLab, Bitbucket - automatik olaraq README-ni ana projekt saytına qaytarır. Bu, hər bir geliştiricinin repositoryya daxil olduğunda gördükləri ilk şeydir. buna baxmayaraq, README-lər sıklıqla şaşırtıcı şəkildə boşdur, ağrılı-yavaşlaşmışdır, ya da qorxulu “TODO: yazma dokumentasiyası daha sonra” ilə doldurulmuşdur. Bu, ən çox oxumağa ehtiyac duyulan dokumentdir, çünki VVD - Hollandiyada futbolçu bu adla tanımır, orada VVD daha çox mərkəz-sağı təmsilən edən siyasi partiyanın adının qısaltması kimi bilinir - artıq sorğu-suala ehtiyacı olmayan ulduzdu. zero clicks Yaxşı yazılmış bir README, bir projektlə qarşılaşdıqdan ilk birkaç dəqiqə ərzində yaradıcının ən vacib soruşmalarına cavab verməlidir: 
 
 
 
 
 
 
 Bu xidmət/projekt/komponent nə işləyir? - Qiymətli bir nişanə və kontekst açıqlaması - heç bir marketinq flüss yoxdur. Onu yerdə necə çalışdıra bilərəm? - Runtime talimatları, çevrimiçi variabillər, bağımlılıq setupları və hər hansı bir projektspecifik komandalar. Bunu necə test edə bilərəm? - Unit testləri, integrasiya testləri, test verilişləri və testlə bağlı hər hansı alətlər. Proqramın strukturu necədir? - direktoriyanın dizaynı, əsas modulları və kodun önemli parçalarını necə tapmaq üçün kısa bir izahdır. Onu necə dağıtmalıyım?Skriptlər, CI / CD notları, ehtiyacı olan izni və ya platformu nüansları. Niyə daha çox oxuyuram? - generated docs, architecture notes, API references, and centralized design documents. README projektin qapısıdır. o, gözləmələr yaratır, onboarding vaxtını azaldır və hər yeni və ya deneyimli mühitçi üçün açıq bir orijinal göstəricidir. düzgün saxlandıqda, bütün repositoryunda ən qiymətli tek dokument olur. 3. JavaDocs – Docs That The Compiler Annoys You Into Maintaining JavaDocs - genellikle görünməz, çox vaxt unutulmuş, lakin bir şey qırıldıqda tamamilə əsaslıdır. Praktikda, Java projektlərinin dokumentasiyası sıklıqla iki ekstremə düşür: ya və ya Çünki “Kod öz-dokumentlaşdırılır”.Həqiqət, hər zaman olduğu kimi, ortada bir yerdədir. over-commenting every trivial line no comments at all “Projektimiz üçün dokumentasiya etmək üçün bilinçli qərar verdik. Bu deməkdir ki: only what was genuinely necessary 
 
 
 
 
 “Domain Terms”in iş spesifikasiyasında olanları tam olaraq eşidib. Əvvəlki yazıNeftçi niyə açıqlama verməyib, niyə açıqlama verməyib Ana səhifə / Siyasət / Siyasətlər / Siyasətlər / Siyasətlər / Siyasətlər / Siyasətlər “Qəbələ”nin “Qəbələ”nin “Qəbələ”nin “Qəbələ”nin “Qəbələ”nin “Qəbələ”nin “Qəbələ”nin “Qəbələ”nin “Qəbələ”nin “Qəbələ”nin “Qəbələ”nin “Qəbələ”nin “Qəbələ”nin “Qəbələ”nin “Qəbələ”nin “Qəbələ”nin “Qəbələ”nin “Qəbələ”in “Qəbələ”in “Qəbələ”in “Qəbələ”in “Qəbələ”in “Qəbələ”in “Qəbələ”in “Qəbələ”in “Qəbələ”in “Qəbələ”in “Qəbələ”in”in “Qəbələ”in “Qəbələ”in”in “Qəbələ”in”in “Qəbələ”in JavaDocs, düzgün istifadə edildiyi zaman, kodu qarışdırmaq olmadan niyyətini açıqlayan mikro-level dokumentasiyası kimi işləyir. 
 
 Kompüterlər syncdən çıxdıqları zaman şikayət edirlər. Əgər bir parametrin adını dəyişdirsəniz, JavaDoc etiketi unutursanız, build sizi xatırlayır. Əgər bir metodu silirsəniz, lakin yazışma referanslarını qoyursanız, IDE bir Noel ağacı kimi aydınlanacaq. Bu yumuşac qırılma, JavaDocs-ların digər dokumentasiya formalarından daha doğrudur - onları gözləmək çətindir. Hər şeyi centralizasiya etmək və “dokumentasiya adaları”ndan qaçmaq üçün, biz də . Doxygen Doxygen yazılım geliştirməsində yaygın olaraq istifadə edilən bir dokumentasiya generator alətdir. C++ topluluğunda ilk olaraq istifadə olunanda, JavaDocs-ı bir HTML sayfa olaraq birləşdirmək üçün istifadə etdik. JavaDoc-ın təqdim etmədiyi bir çox xüsusiyyətlər var, bəlkə, hierarşiyalar və işbirliği kontekstləri üçün sınıf diagramları, daha çox öhdəlik sayfaları və daha çox. Bu, bizə bütün kod bazasının təmiz, birləşmiş görünüşünü verirdi, dağılıb IDE ipuçlarına təslim olmadan. 4. Clean Code – The Documentation You Don’t Need to Maintain Son olaraq, ən az qiymətləndirilən dokumentasiya forması da, həqiqətən də ehtiyacı olmadan geliştiricilər üçün ən az sayılan formadır: clean code. Əsas səhifə » Xəbərlər » Əsas səhifə » Əsas səhifə » Əsas səhifə Amma yaxşı yazılmış kodu – açıq, nifrətli və ifadəçi – Dokumentlər İŞİD Uncle Bob bu sözləri belə yazır: “Clean code reads like well-written prose”. pratikdə bu anlamına gəlir: 
 
 
 
 
 
 
 Onların adları və adları var ki, onların Bir şeyi edə bilən və onu yaxşı edə bilən Bütün terminoloqlarda sistematik olaraq istifadə olunur Kimsə özü üçün dəhşətli deyil “Sürpriz davranışlar” içərisində gizli yan effektlər yoxdur Düşünmək üçün PhD-yə ehtiyacı olmayan ehtiyacsız derin abstraksiya “Clean code” sistemin refaktorları, sprinterləri, personelin qarışıqlığı və organizasiya kaosunu ədalətləndirmək üçün garantlu olan tek artefaktdir. Bu sistemin davranışı. is Zamanla bizim üçün basit bir norm ortaya çıxdı: If you need a paragraph of comments to explain a method, the real problem is the method. Kod expressiv olduğunda, hər şey daha asan olur → JavaDocs daha asan və daha fokuslı olur → README azalıb, çünki onboarding açıq olur → spesifikasiya daha açıq olur, çünki domen modeli iş sözlükləri yansıdı. Clean code doesn’t eliminate the need for documentation; it  Bunu Ankarada Bu, bütün digər dokumentasiya formalarının (specs, READMEs, JavaDocs) həqiqəti təsdiq etmədən, açıq-aşkar implementasiyaların kompensasiya edilməsini təmin edir. Son olaraq, təmiz kodu sistemin həqiqətən nə etdiyinin ən həqiqi və güvenilir açıqlamasıdır. Bringing It All Together — A Living Documentation Pipeline Hər şeyi bir-birinə gətirmək - canlı dokumentasiya boru hattı “Dokumentasiyalarımızı necə yazdıqlarını yaxşılaşdırdıqdan sonra, son adım yalnız yaradılmamasıdır – ancaq davamlı olaraq göndərilməlidir və hər zaman əldə edilə bilər.Bu üçün, spesifikasiyalarımızı, README dosyalarımızı və JavaDocs-u tək bir birimə çevirən bir dokumentasiya kanalı qurduq. . living documentation portal İstədiklərimiz kodumuzla mümkün olduğunca yaxın yaşamaqdıqca, hər şeyə daxil olmaya karar verdik. “GitLab”, bizə çətindir, versiyadan kontrol edilmiş hosting çözümü doğrudan kod bazasına bağlı oldu. “GitLab Pages” “GitLab” üçün özəl deyil (GitLab, örnək kimi, də “GitLab” sayfaları var) – bu popüler versiyası kontrol sistemlərinin bir başqa düzgün xüsusiyyətidir ki, daha da oxumaq üçün tavsiye edirəm – . GitHub Pages Linklər Bütün bunları bir araya gətirmək üçün bir neçə sayfa hazırladıq. Sphinx. Sphinx is a powerful documentation generator written in Python. It takes source files written in reStructuredText or Markdown and translates them into various output formats, including HTML, PDF, and ePub. Sphinx strukturu, navigasiya və temalarla işlədi. Doxygen Sphinx-i otomatik olaraq yaradılan JavaDocs-larla istifadə edib. VVD - Hollandiyada futbolçu bu adla tanımır, orada VVD daha çox mərkəz-sağı təmsilən edən siyasi partiyanın adının qısaltması kimi bilinir - artıq sorğu-suala ehtiyacı olmayan ulduzdu. Həyat Hər bir əsasla birləşmək, dosyaları yeniləmək üçün bir CI işinə yol açdı, portalın sonuncu kodu dəyişikliklərini, API güncellemələrini və dizayn kararlarını yansıtdığını təmin etdi. Hiç bir şey izolasiya altında yaşayıb. Hiç bir şey manual sinxrasiya lazımdır. Bu, dokumentasiyamızı statik bir artefaktdan həmişə güncellenən ekosistemə çevirir, ki, bu, geliştiricilərin istifadə etdiyi bir ekosistemdir, çünki doğrudan günlük iş proseslərinə endirildi və kodun yanında yaşayırdı. Conclusion — Documentation Is Our Responsibility, Not Our Burden “Dokumentasiya bizim sorğumuzdur, bizim yükümüz deyil” Günün sonunda, yazma dokumentasiyası seçicilik deyil. Bu, inqilab professionalları kimi bizim işimizin bir parçasıdır. Gələcək komandalar buna bağlıdır. Onboarding buna bağlıdır. Bakım, güvenilirlik və hətta arkitektonik açıqlıq buna bağlıdır. “Dokumentləri kodun yaxınlığında saxlayaraq, avtomatikləşdirə biləcəyimiz hər şeyi avtomatiklaşdıraraq, Markdown, JavaDocs, Doxygen və Sphinx kimi smart alətlərə təvəkkül etməklə, normaldır ki, dokumentasiya işlərini öldürən çirkinlikdən qurtuluruq. Dokumentasiyanın mükəmməl olması lazım deyil – yalnız qabiliyyətli, doğru və canlı olmalı, sistemlər yaratdığımız zaman programcıların kod yazdıqları kimi dosyaları yeniləməyə kömək edən sistemlər yaratdığımız zaman hər kəs faydalana bilər: komanda, məhsul və ən böyük şey, 6 ay sonra proqnozun mirası olan pis ruh. Yaxşı dokumentasiya bizi daha az lənətləndirməzdir. Yalnız lənətləndirmək böyük proqramlar yaratmaqla uyğundur.

The is an opinion piece based on the author’s POV and does not necessarily reflect the views of HackerNoon.

Every

Front

Read My Stories

Bu audio hekayənin orijinal dilində hazırlanmışdır!

Əgər dokumentasiyanız iki kliklə açılırsa, toplanır - o, artıq ödənilmişdir

About Author

ŞƏRHLƏR

ETİKET ASIN

BU MƏQALƏ TƏQDİM EDİLMİŞDİR

Related Stories

Women in Tech: Azize Sultan Shares Her Inspiring Journey from Architecture to Tech Leadership

How Azarus's Technology is Transforming Viewer Engagement on Stream

Optimizing Operations for Real Estate Investors - Interview with Startups of the Year Nominee, Azibo

Women in Tech: Azize Sultan Shares Her Inspiring Journey from Architecture to Tech Leadership

How Azarus's Technology is Transforming Viewer Engagement on Stream

Optimizing Operations for Real Estate Investors - Interview with Startups of the Year Nominee, Azibo

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps