आइए ARCHITECTURE.md जोड़ें

 (matklad.github.io)
26 पॉइंट द्वारा xguru 2021-02-08 | 1 टिप्पणियां | WhatsApp पर शेयर करें

  • ओपन सोर्स में योगदान को आसान बनाने के लिए, प्रोजेक्ट की architecture समझाने वाली फ़ाइल को repo में जोड़ने का सुझाव देने वाला लेख

  • प्रोजेक्ट में कभी-कभार योगदान देने वाले व्यक्ति और core developer के बीच सबसे बड़ा अंतर प्रोजेक्ट की architecture की समझ है

  • अगर आप structure से परिचित नहीं हैं, तो patch लिखने में 2 गुना से अधिक समय लग सकता है, लेकिन कहाँ बदलाव करना है यह पता लगाने में 10 गुना से अधिक समय लगता है

  • उच्च-स्तरीय architecture समझाने वाली ARCHITECTURE.md जैसी फ़ाइल लिखें

→ इसे छोटा रखें ताकि कोई भी इसे पढ़ सके, और केवल उन हिस्सों को व्यवस्थित करें जो अक्सर नहीं बदलते

→ इसे code के साथ पूरी तरह sync करने की कोशिश न करें, बस साल में लगभग दो बार दोबारा देखें

इसे लिखने का तरीका

  • जिस समस्या को हल किया जा रहा है, उसके bird's-eye view से शुरू करें

  • थोड़ा अधिक विस्तृत code map: "X करने वाली चीज़ कहाँ है?"

  • मोटे तौर पर modules और उनके संबंध समझाएँ: हर module क्या करता है, इसके लिए दूसरे दस्तावेज़ों से लिंक करें

  • महत्वपूर्ण files, modules, types के नाम लिखें

→ ताकि पढ़ने वाला नाम से search कर सके, और सीधे लिंक न दें (वे टूट सकते हैं)

  • layers और systems के बीच की boundaries स्पष्ट करें
  • अच्छे उदाहरण

संबंधित पढ़ाई

1 टिप्पणियां

 
xguru 2021-02-08

और main README.md में अगर संभव हो तो प्रोजेक्ट के हर फ़ोल्डर के बारे में विवरण जोड़ने का सुझाव भी अच्छा है

उदाहरण: https://github.com/diem/diem/…

अगर संभव हो तो हर फ़ोल्डर में विवरण जोड़ें, और अगर GitHub फ़ोल्डर में README होने पर उसका कंटेंट ऊपर से दिखाए तो वह भी अच्छा होगा

इस संदर्भ में Architecture Decision Records को भी देखें