README yangu ilisema zana 80. Code yangu ilikuwa na 96. Hakuna aliyegundua kwa wiki kadhaa.
Ninaendesha mradi wa chanzo huru (open-source). Unatumia otomatiki ya kivinjari (browser automation) kwa ajili ya mawakala wa AI.
README yangu ilisema mradi una zana 80. Niliweka namba hiyo kwenye kauli mbiu (tagline), sehemu ya urambazaji (navigation), na maandishi ya mitandao ya kijamii.
Wiki iliyopita nilifanya ukaguzi (audit). Nilikilinganisha README yangu na code yangu halisi.
Code ilionyesha zana 96.
Nilikuwa na ukweli mitatu tofauti katika faili moja:
- Namba ya masoko: 80
- Orodha iliyoelezwa: 83
- Code halisi: 96
Zana kumi na tatu hazikuwa na maelezo kabisa. Watumiaji hawakujua kama zipo.
Sehemu hatari zaidi ilikuwa pengo hilo. Nne kati ya zana hizo zisizoelezwa zilikuwa zana za mfumo za kiwango cha juu (high-level system tools). Zilitumia matukio ya kiwango cha OS kudhibiti kibodi na panya (mouse). Hii ndiyo sehemu yenye nguvu na nyeti zaidi ya mradi wangu.
Hii ilinifundisha somo gumu kuhusu mabadiliko ya nyaraka (documentation drift).
Mabadiliko hayo si ya nasibu. Yana upendeleo. Unatoa maelezo kwa vitu rahisi na vya kuchosha. Unasahau kutoa maelezo kwa zana mpya, zenye nguvu, au nyeti unazozituma kwa haraka.
Ikiwa unataka kupata sehemu yenye hatari zaidi ya mradi, usisome nyaraka (docs). Angalia pengo kati ya nyaraka na code.
Nilijaribu kurekebisha namba hiyo. Hiyo ilikuwa kosa. Kurekebisha namba kunatibu dalili tu.
Tatizo ni matengenezo ya mikono (manual maintenance). Ikiwa binadamu ataandika ukweli fulani, ukweli huo hatimaye utakuwa si sahihi.
Suluhisho pekee la kweli ni kufanya iwe vigumu kupata namba isiyo sahihi.
Lazima utoe ukweli kutoka kwenye chanzo cha ukweli (source of truth).
Mradi wangu tayari ulikuwa na suluhisho moja: smoke test. Jaribio hilo huuliza seva ni zana ngapi inazo na kulinganisha idadi hiyo. Halitumii namba iliyoandikwa moja kwa moja (hardcoded number). Jaribio hilo haliwezi kamwe kupoteza usahihi kwa sababu halihifadhi namba tuli (static number).
Acha kujaribu kuwa na nidhamu zaidi katika uandishi wako. Nidhamu hushindwa. Badala yake, weka ukweli wako kuwa wa kiotomatiki (automate):
- Tengeneza idadi kwa kutumia skripti wakati wa ujenzi (build time).
- Tengeneza orodha ya zana moja kwa moja kutoka kwenye rejista ya code yako.
- Tumia binadamu kwa ajili ya maelezo na simulizi pekee.
Ikiwa ukweli unaweza kupatikana kwa njia ya kutoa (derivable), usiuandike kwa mkono. Ni mabadiliko tu yanayosubiri kutokea.
Fanya ukaguzi huu kwenye mradi wako mwenyewe leo:
- Hesabu vitu halisi katika code yako.
- Hesabu kile ambacho nyaraka zako zinadai.
- Ikiwa hazikubaliani, tafuta ni nini kipo kwenye pengo hilo.
Vitu vilivyopo kwenye pengo mara nyingi ndivyo sehemu muhimu zaidi za mradi wako.
Optional learning community: https://t.me/GyaanSetuAi