Kwa miaka, nimefanya kazi juu ya miradi ya aina zote - kubwa, ndogo, chaotic, overengineered, "kuwa ya muda mrefu", inayojulikana kuwa iliyoundwa vizuri, na kila kitu kati yake. The documentation is always missing, outdated, or buried in some forgotten corner of Confluence guarded by a 2019 timestamp. Kila mradi wa kuwa na nyaraka. madai ya Kila timu ya wataendelea kuwa na update. ahadi ya Na kila mtengenezaji anasema kwa ujasiri, "Usiogope, nitakuandika baadaye," ambayo, kama sisi wote tunajua, ni nyaraka sawa na kusema “Ndiyo, cheque ni kwenye barua pepe.” Baada ya kuona mzunguko huu wa kurudia tena mara nyingi zaidi kuliko ningependa kukiri, nilielewa kitu rahisi lakini cha kweli: 
 
 Takwimu inaweza kuishi tu ikiwa inaishi karibu na nambari iwezekanavyo - kwa sababu watengenezaji (ikiwa ni pamoja na mimi mwenyewe) ni viumbe wasio na ujasiri. Documentation only survives if it lives as close to the code as possible—because developers (myself included) are lazy creatures. Na kutokana na hilo, ufahamu mwingine ulikuja - tatizo kuu la nyaraka za zamani ni ukweli kwamba timu nyingi hazichukuliwi kama sehemu ya mzunguko wa maendeleo kuu, kuacha kwa baadaye au kufanya kwa sababu ya vipengele vichache vya pre-dev ambazo tayari zilikuwa na mahali fulani katika Confluence. Ili kuandika nyaraka muhimu, hebu kwanza kujadili aina gani ya nyaraka kuna kwa sehemu ya programu: Ways to Document Code (That Developers Might Actually Use) Njia za Kodi ya Takwimu (Kwa ambayo watengenezaji wanaweza kutumia) Mara baada ya kukubali kwamba nyaraka lazima kuishi karibu na msimbo, swali la pili ni kwa ajili ya muundo wake. jinsi ya Katika mazoezi, nimeona kuwa nyaraka nzuri sio kiini kimoja - ni mazingira madogo ya ngazi, kila mmoja anayehudumia madhumuni tofauti na watazamaji. Kwa mradi huo niliyosema (iliyoandikwa katika Java + Spring Boot), tuligundua aina nne kuu za docs: 1. Client Specs Hizi ni nyaraka za kawaida za kawaida zilizokusanywa na mtaalam wa kikoa. Kwa njia bora, ni tajiri na lugha ya kila mahali na hutoa maelezo ya code-agnostic ya kesi za biashara - kwa maneno mengine, kila kitu ambacho mhandisi anahitaji kuelewa kweli tatizo la mkono. Kwa bahati mbaya, katika hali halisi, nyaraka hizi mara nyingi huhifadhiwa mahali fulani katika Confluence, kushirikiana na timu mwanzoni mwa mradi, na kisha karibu kamwe updated tena. Usiwe na makosa: nyaraka hizi ya muhimu. ya Kupata ujuzi kutoka kwa wataalamu wa uwanja unapaswa kuwa kipaumbele cha juu kwa timu yoyote ya uhandisi. Lakini taratibu zinabadilika, muda mfupi unazingatia kila mtu, na nyaraka hizo za awali polepole lakini kwa uhakika zinakuwa msingi wa zamani. Ujuzi wa mahitaji yanayobadilika, kesi za upana, na pivot ya mradi huenda kuishi katika msimbo - au mbaya zaidi! - katika kichwa cha watengenezaji wa juu. Ili kukabiliana na hili, tumeacha kuandika maelezo katika faili za random ya Word au kurasa za Confluence zinazopangwa kusahau na kuhamia karibu na mstari wa mbele iwezekanavyo: the code repository. Tumeanza kuhifadhi kama faili za Markdown (.md) ndani ya repo, kwa kawaida katika docs / folda. Katika mazingira makubwa ya microservice, nyaraka hizi zinaweza hata kuhalalisha hifadhi ya kujitolea inayohusishwa kama submodule ya Git. Kwa kusoma zaidi juu ya submodules, ninapendekeza sana chapisho hili la blogu - . Link ya 2. README – The Front Door for Humans Ikiwa maelezo ya wateja ni encyclopedia, README ni mlango wa mbele. na hata hivyo, ni mojawapo ya nyaraka zilizopangwa zaidi katika miradi ya programu. Kwa bahati mbaya, karibu kila jukwaa la udhibiti wa toleo - GitHub, GitLab, Bitbucket - moja kwa moja huonyesha README moja kwa moja kwenye ukurasa wa mradi mkuu. Ni kitu cha kwanza mtu yeyote anayeona wakati wa kuingia katika hifadhi. Ni hati moja ambayo inawezekana zaidi kusomwa kwa kweli kwa sababu inahitaji Na kwa sababu iko kwenye mizizi ya repo, watengenezaji wana uwezekano mkubwa wa kuboresha wakati wa kufanya kazi juu ya msimbo. zero clicks README iliyoandikwa vizuri inapaswa kujibu maswali muhimu zaidi ambayo mwanzilishi ana ndani ya dakika chache za kwanza za kukutana na mradi: 
 
 
 
 
 
 
 Huduma hii / mradi / sehemu inafanya nini? - lengo la mfupi na taarifa ya mazingira - hakuna mtiririko wa masoko. Jinsi ya kuendesha ndani? - maagizo ya muda wa kuendesha, variables ya mazingira, usanidi wa kujitegemea, na maagizo yoyote ya mradi maalum. Jinsi ya kujaribu? - majaribio ya kitengo, majaribio ya ushirikiano, kuanzisha data ya majaribio, na zana yoyote inayohusiana na majaribio. Jinsi mradi ni muundo? - ufafanuzi mfupi wa muundo wa mapitio, modules muhimu, na wapi kupata sehemu muhimu za msimbo. Jinsi ya kuwasilisha? maandishi ya kuwasilisha, kumbukumbu za CI / CD, ruhusa zinazohitajika, au nuances ya jukwaa. Ninaweza kusoma zaidi wapi? - viungo kwa dosari zilizozalishwa, kumbukumbu za usanifu, viungo vya API, na nyaraka za kubuni za kituo. README ni njia ya kuingia katika mradi. Inaweka matarajio, hupunguza muda wa kuingia, na hutoa kila mhandisi - mpya au mwenye ujuzi - mtazamo wazi. 3. JavaDocs – Docs That The Compiler Annoys You Into Maintaining JavaDocs - kawaida isiyojulikana, mara nyingi kusahau, lakini muhimu kabisa wakati kitu kinatokea. Katika mazoezi, kumbukumbu ya miradi ya Java mara nyingi huanguka katika mipaka miwili: au au ya Kwa sababu "mfano ni mwenyewe-dokumenting." Ukweli, kama daima, ni mahali fulani katikati. over-commenting every trivial line no comments at all Kwa mradi wetu, tumefanya uamuzi uliofahamika wa kuandika Hii inamaanisha kuwa: only what was genuinely necessary 
 
 
 
 
 kutumia lugha ya kila mahali ili maneno ya kikoa yamefanana na kile kilichokuwa katika maelezo ya biashara kuelezea kwa nini nyuma ya maamuzi yasiyo ya wazi, sio kile ambacho kanuni tayari inafichua kumbukumbu ya darasa la msingi la kikoa, interfaces, na kazi ngumu kuepuka ukuta wa maoni ambao tu kurudia jina la mbinu katika fomu ya verbose JavaDocs, wakati kutumika kwa usahihi, inatumika kama nyaraka ya kiwango cha micro ambazo zinafafanua nia bila kuharibu msimbo. Na tofauti na kurasa za Confluence, JavaDocs zinakuja na faida ya ndani: 
 
 Mwandishi kwa kweli anasisitiza wakati wao kupata nje ya sync. Ikiwa unabadilisha jina la kiwango lakini unasahau alama ya JavaDoc, uumbaji unakumbuka. Ikiwa unatoweka mbinu lakini uacha viungo vya maoni, IDE inakua kama mti wa Krismasi. Shinikizo hili ndogo ni kwa nini JavaDocs huwa na uhakika zaidi kuliko aina nyingine za nyaraka - ni ya kutisha kusahau. Ili kudumisha kila kitu kikatili na kuepuka "mji wa kumbukumbu," pia tulitumia . Doxygen Doxygen ni kifaa kinachotumiwa sana katika maendeleo ya programu. Wakati hasa hutumiwa katika jumuiya ya C++, tulitumia kuunganisha JavaDocs katika kiungo kinachotembea - ukurasa wa HTML. Ina vipengele kadhaa ambazo JavaDoc haitoi, kwa mfano, chaguzi za darasa kwa maagizo na mazingira ya ushirikiano, kurasa zaidi za muhtasari, na zaidi. Hii iliwapa mtazamo safi, wa pamoja wa kanuni nzima bila kutegemea vidokezo vya IDE vilivyoenea. 4. Clean Code – The Documentation You Don’t Need to Maintain Hatimaye, aina ya usahihi zaidi ya nyaraka pia ni moja ambayo watengenezaji heshima kidogo mpaka wanahitaji kweli: clean code. Maoni ya umri. Specs drift. READMEs kupuuzwa. JavaDocs inaweza kuwa stable. Lakini msimbo ulioandikwa vizuri - wazi, kwa makusudi, na wazi - ya nyaraka. ya Kama Baba Mtakatifu alivyosema, "Msimbo safi inasoma kama maandishi yaliyoandikwa vizuri." Katika hali halisi, hii inamaanisha: 
 
 
 
 
 
 
 Masomo na mbinu na majina ambayo yanaonyesha madhumuni yao kazi ambayo hufanya kitu kimoja na hufanya vizuri Domain terminology kutumika kwa utaratibu wote Hakuna ujuzi kwa ajili yake mwenyewe Hakuna "hisi ya kushangaza" imefichwa ndani ya madhara ya upande hakuna abstractions kinachohitajika ambayo inahitaji PhD kuelewa Kodi safi ni kipengele kimoja kilichohifadhiwa kuishi refactors, sprints, biashara ya wafanyakazi, na machafuko ya shirika. Ni daima katika usawa na tabia ya mfumo kwa sababu - ni tabia ya mfumo. is Kanuni rahisi ilionekana kwetu kwa muda: If you need a paragraph of comments to explain a method, the real problem is the method. Wakati msimbo ni expressive, kila kitu kinaweza kuwa rahisi → JavaDocs kuwa mwanga na zaidi lengo → README inapungua kwa sababu onboarding inakuwa dhahiri → taratibu huwa wazi zaidi kwa sababu mfano wa kikoa inaonyesha maneno ya biashara. Kodi safi haina kuondoa haja ya kumbukumbu; ni ya hiyo. Maana ya Anchors Inahakikisha kwamba aina nyingine zote za nyaraka - specs, READMEs, JavaDocs - ni kuimarisha ukweli badala ya kulipa kwa utekelezaji usio wazi. Hatimaye, msimbo safi ni nyaraka ambazo hazihitaji utunzaji, hakuna ushirikiano wa CI, na hakuna zana. Bringing It All Together — A Living Documentation Pipeline Kutoa Vitu Vyote Pamoja - Utaratibu wa Utaratibu wa Kuishi Baada ya kufafanua jinsi tulivyoandika nyaraka, hatua ya mwisho ilikuwa kuhakikisha kwamba haikuwa tu iliyoundwa—lakini ilipelekwa mara kwa mara na daima inapatikana. . living documentation portal Kwa kuwa tulitaka nyaraka zetu kuishi karibu na msimbo wetu iwezekanavyo, tumeamua kutumia kila kitu kupitia Github Pages sio maalum kwa Github (GitLab, kwa mfano, pia ina kurasa za GitLab) - ni kipengele kingine cha mifumo maarufu ya usimamizi wa toleo na nataka kusoma zaidi - . GitHub Pages Link ya Ili kuunganisha kila kitu katika seti ya kurasa za pamoja, tulitumia Sphinx. Sphinx ni jenereta yenye nguvu ya nyaraka iliyoandikwa katika Python. Inachukua faili za chanzo zilizoandikwa katika reStructuredText au Markdown na kutafsiri kwa muundo tofauti wa output, ikiwa ni pamoja na HTML, PDF, na ePub. Sphinx alihusika na muundo, uendeshaji, na mandhari. Doxygen ilitoa Sphinx na JavaDocs zilizoundwa moja kwa moja kutumia Plugin, ambayo inatuwezesha kuvinjari API moja kwa moja kutoka kwenye msimbo wa chanzo. Wakati huo huo, root README ilitumika kama hatua ya haraka ya kuingia kwa watengenezaji wa kuchunguza repository, kuunganisha kwa urahisi kwenye tovuti ya nyaraka iliyotengenezwa. Roho ya Kila mchanganyiko katika msingi ulisababisha kazi ya CI ambayo ilijenga upya doses, kuhakikisha kwamba jukwaa lilionyesha mabadiliko ya hivi karibuni ya msimbo, updates ya API, na maamuzi ya kubuni. Hakuna kilikuwa kimoja. Hakuna kilichohitaji usindikaji wa mikono. Hii ilibadilisha usajili wetu kutoka kwa unyanyasaji wa static hadi mfumo unaoendelea unaotumika ambayo watengenezaji waliitumia kwa kweli, kwa sababu ilikuwa imeunganishwa moja kwa moja katika mtiririko wao wa kila siku wa kazi na kuishi pamoja na msimbo. Conclusion — Documentation Is Our Responsibility, Not Our Burden Ufafanuzi – Ufafanuzi ni wajibu wetu, sio uzito wetu Mwisho wa siku, kuandika nyaraka sio chaguo. Ni sehemu ya kazi yetu kama wataalamu wa uhandisi. Wateja wa timu wa baadaye hutegemea. Kuingia inategemea. Uhifadhi, kuaminika, na hata uwazi wa usanifu hutegemea. Lakini kukubali jukumu hilo haimaanishi kwamba nyaraka lazima iwe mbaya. Kwa kuweka doses karibu na nambari, automatisering chochote kinachoweza kuwa na automatisering, na kutegemea zana smart kama Markdown, JavaDocs, Doxygen, na Sphinx, sisi kuondoa friction ambayo kawaida kuua jitihada za kumbukumbu. sisi kurekebisha kitu ambacho kawaida inaonekana kama kazi katika kuendeleza asili ya maendeleo ya kila siku. Takwimu haipaswi kuwa kamili - inahitaji tu kuwa inapatikana, sahihi, na hai.Kama tunajenga mifumo ambayo inahamasisha watengenezaji kuboresha nyaraka kwa urahisi kama wanaandika msimbo, kila mtu hupata faida: timu, bidhaa, na muhimu zaidi, nafsi maskini ambaye anamiliki mradi miezi sita baadaye. Takwimu nzuri haina kufanya sisi kidogo kidogo. Hiyo tu hufanya kuwa kidogo kukabiliana na kujenga programu kubwa.

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

Sauti hii imetolewa katika lugha asilia ya hadithi!

Ikiwa kumbukumbu yako inachukua click mbili kufungua, Congrats - Ni tayari iliyopita

About Author

MAONI

HANG TAGS

MAKALA HII ILIWASILISHWA NDANI

Related Stories

Jinsi $ TRUTH token ya Swarm Network inapanga kukabiliana na taarifa mbaya kupitia uhakiki wa Blockchain

Sweet Security Unveils First Unified Detection And Response Platform

Master Crypto Security: Your Complete Guide to Safe Wallet Management

#ellenBrain Turns a Long Weekend Into: HackerNoon Swag Around the World

Jinsi $ TRUTH token ya Swarm Network inapanga kukabiliana na taarifa mbaya kupitia uhakiki wa Blockchain

Sweet Security Unveils First Unified Detection And Response Platform

Master Crypto Security: Your Complete Guide to Safe Wallet Management

#ellenBrain Turns a Long Weekend Into: HackerNoon Swag Around the World

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps