माझ्या README मध्ये ८० टूल्स होते. माझ्या कोडमध्ये ९६ होते. अनेक आठवडे कोणाचेही लक्ष गेले नाही.

मी एक ओपन-सोर्स प्रोजेक्ट चालवतो. हे AI एजंट्ससाठी ब्राउझर ऑटोमेशनचा वापर करते.

माझ्या README मध्ये असे म्हटले होते की प्रोजेक्टमध्ये ८० टूल्स आहेत. मी ती संख्या टॅगलाईन, नेव्हिगेशन आणि सोशल मीडिया टेक्स्टमध्ये वापरली होती.

गेल्या आठवड्यात मी एक ऑडिट केले. मी माझ्या README ची माझ्या प्रत्यक्ष कोडशी तुलना केली.

कोडमध्ये ९६ टूल्स नोंदवले गेले होते.

एकाच फाईलमध्ये माझ्याकडे तीन वेगवेगळी सत्ये होती:

  • मार्केटिंगची संख्या: 80
  • डॉक्युमेंटेड लिस्ट: 83
  • प्रत्यक्ष कोड: 96

तेरा टूल्स पूर्णपणे डॉक्युमेंटेड नव्हते. ते अस्तित्वात आहेत हे वापरकर्त्यांना माहितच नव्हते.

सर्वात धोकादायक भाग म्हणजे तो फरक (gap). त्या डॉक्युमेंट न केलेल्या टूल्सपैकी चार हाय-लेव्हल सिस्टम टूल्स होते. कीबोर्ड आणि माऊस नियंत्रित करण्यासाठी ते OS-लेव्हल इव्हेंट्सचा वापर करत होते. हा माझ्या प्रोजेक्टचा सर्वात शक्तिशाली आणि संवेदनशील भाग आहे.

यातून मला 'documentation drift' बद्दल एक कठीण धडा मिळाला.

ड्रिफ्ट (Drift) हे यादृच्छिक नसते. ते पूर्वग्रहदूषित असते. तुम्ही सोप्या आणि कंटाळवाण्या गोष्टी डॉक्युमेंट करता. घाईघाईत तुम्ही पाठवलेली नवीन, शक्तिशाली किंवा संवेदनशील टूल्स डॉक्युमेंट करायला तुम्ही विसरता.

जर तुम्हाला एखाद्या प्रोजेक्टचा सर्वात जोखमीचा भाग शोधायचा असेल, तर डॉक्युमेंटेशन वाचू नका. डॉक्युमेंटेशन आणि कोडमधील फरक (gap) पहा.

मी ती संख्या सुधारण्याचा प्रयत्न केला. ती एक चूक होती. फक्त संख्या सुधारणे म्हणजे केवळ लक्षणांवर उपचार करणे आहे.

समस्या मॅन्युअल मेंटेनन्सची आहे. जर एखादा माणूस एखादी माहिती टाईप करत असेल, तर ती माहिती कालांतराने चुकीची ठरेलच.

एकमेव खरा उपाय म्हणजे संख्या चुकीची येणे अशक्य करणे.

तुम्हाला 'source of truth' मधून तथ्ये मिळवावी लागतील.

माझ्या प्रोजेक्टमध्ये आधीच एक उपाय होता: smoke test. ही टेस्ट सर्व्हरला विचारते की त्याच्याकडे किती टूल्स आहेत आणि मग ती संख्या तपासते. ती कोणत्याही hardcoded नंबरचा वापर करत नाही. ही टेस्ट कधीही ड्रिफ्ट होऊ शकत नाही कारण ती कधीही स्टॅटिक नंबर साठवत नाही.

तुमच्या लेखनात अधिक शिस्त आणण्याचा प्रयत्न करणे थांबवा. शिस्त अपयशी ठरते. त्याऐवजी, तुमची तथ्ये ऑटोमेट करा:

  • बिल्ड टाइमला स्क्रिप्ट वापरून संख्या जनरेट करा.
  • तुमच्या कोड रजिस्ट्रीमधून थेट टूल्सच्या लिस्ट जनरेट करा.
  • केवळ गद्य (prose) आणि स्पष्टीकरणासाठी माणसांचा वापर करा.

जर एखादे तथ्य काढता येण्यासारखे (derivable) असेल, तर ते हाताने टाईप करू नका. ते फक्त ड्रिफ्ट होण्याची वाट पाहत आहे.

आजच तुमच्या स्वतःच्या प्रोजेक्टवर हे ऑडिट करा:

  1. तुमच्या कोडमधील वास्तविक गोष्टी मोजा.
  2. तुमचे डॉक्युमेंटेशन काय दावा करते ते मोजा.
  3. जर त्यामध्ये तफावत असेल, तर त्या फरकात काय आहे ते शोधा.

त्या फरकातील गोष्टी सहसा तुमच्या प्रोजेक्टचे सर्वात महत्त्वाचे भाग असतात.

Source: https://dev.to/achiya-automation/my-readme-said-80-tools-my-code-had-96-nobody-noticed-for-weeks-1f3e

Optional learning community: https://t.me/GyaanSetuAi