"Architecture.md (2021)" तकनीकी विनिर्देशन

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

ARCHITECTURE.md लिखने की सिफारिश

  • open source project maintainers को README और CONTRIBUTING के साथ ARCHITECTURE दस्तावेज़ जोड़ने की जोरदार सिफारिश की जाती है।
  • यह दस्तावेज़ project की high-level architecture को समझाता है, और क्योंकि इसे बार-बार योगदान देने वाले contributors को पढ़ना चाहिए, इसे छोटा रखना बेहतर है।
  • ARCHITECTURE दस्तावेज़ में केवल वही सामग्री होनी चाहिए जो बार-बार नहीं बदलती; इसे code के साथ sync करने की कोशिश करने के बजाय साल में कुछ बार review करना अधिक उपयुक्त है।

दस्तावेज़ का उद्देश्य और महत्व

  • project की physical architecture के बारे में ज्ञान ही सामान्य contributors और core developers के बीच सबसे बड़ा अंतर है।
  • अगर आप project से परिचित नहीं हैं, तो patch लिखने में 2 गुना अधिक समय लगता है, और code बदलने की सही जगह समझने में 10 गुना अधिक समय लग सकता है।
  • ARCHITECTURE फ़ाइल इस अंतर को कम करने का एक प्रभावी तरीका है, और project की संरचना पर पुनर्विचार करने का अवसर भी देती है।

दस्तावेज़ की संरचना

  • इसकी शुरुआत समस्या के एक नए दृष्टिकोण से दिए गए overview से होनी चाहिए, और modules के बीच संबंध समझाने वाला विस्तृत code map देना चाहिए।
  • महत्वपूर्ण files, modules और types का उल्लेख करें, लेकिन सीधे link देने के बजाय नाम से खोजने के लिए प्रोत्साहित करें ताकि maintenance की आवश्यकता न पड़े।
  • architectural invariants को स्पष्ट रूप से इंगित करना चाहिए, और layers के बीच boundaries को भी चिन्हित करना चाहिए।

स्थापत्य invariants और boundaries

  • महत्वपूर्ण invariants अक्सर किसी चीज़ की अनुपस्थिति के रूप में व्यक्त होते हैं, और केवल code पढ़कर उन्हें समझना कठिन होता है।
  • layers या systems के बीच boundaries, system के implementation के बारे में अप्रत्यक्ष जानकारी समेटे होती हैं और सभी संभावित implementations को सीमित करती हैं।

end-to-end concerns

  • code map पूरा करने के बाद, end-to-end concerns के लिए एक अलग section जोड़ना चाहिए।
  • ARCHITECTURE दस्तावेज़ के अच्छे उदाहरण के रूप में rust-analyzer का architecture.md मौजूद है।

GN⁺ की राय:

  • ARCHITECTURE दस्तावेज़ project को समझने में मदद करता है और नए contributors को codebase से जल्दी परिचित कराने में महत्वपूर्ण भूमिका निभाता है।
  • यह दस्तावेज़ project की संरचना को स्पष्ट करता है और महत्वपूर्ण architectural principles तथा boundaries को उभारता है, जिससे developers system को बेहतर समझ पाते हैं।
  • open source community में ARCHITECTURE दस्तावेज़ को अपनाना project की टिकाऊ growth और maintenance में योगदान दे सकता है, और यह developers के लिए एक बेहद उपयोगी और रोचक दृष्टिकोण है।

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

1 टिप्पणियां

 
GN⁺ 2024-02-26
Hacker News टिप्पणियाँ

  • अगर आप एक open source project मैनेज कर रहे हैं और code line 10k-200k के बीच है, तो मैं ARCHITECTURE document जोड़ने की ज़ोरदार सिफारिश करता हूँ।

    • आइडिया अच्छा है, लेकिन मुझे लगता है कि repository के size से अलग, architecture को Readme में शामिल किया जा सकता है। उदाहरण के लिए, मैं जानबूझकर मुख्य Readme में Mermaid sequence diagram रखता हूँ ताकि सभी users workflow समझ सकें।

  • यह approach उन open source projects के लिए कम maintenance वाला शानदार model है जिनमें ad hoc contributors बहुत होते हैं। जिन projects में dedicated engineers होते हैं, उनके लिए ADRs पर विचार करना चाहिए। इसमें ज़्यादा maintenance चाहिए, लेकिन यह "क्यों" और "किन alternatives पर विचार किया गया" को रिकॉर्ड करता है, जिससे दोबारा बनाते समय बहुत मदद मिलती है।

  • कुछ साल पहले मैंने अपने एक बड़े side project में ऐसा ही कुछ प्रयोग किया था:

    • हर file के top पर दूसरे ARCHITECTURE.md files के links का एक tree था।

  • हर IDE project की folder structure को बाईं तरफ standard directory tree के रूप में दिखाता है। क्या कोई ऐसा IDE है जो dependency graph के ज़रिए project को explore करने का support करता हो?

  • यहाँ लेखक ने जो लिखा है, उसे सामान्य software projects पर लागू करते समय सावधानी बरतनी चाहिए। बड़े open source projects, जिनमें बहुत contributors हों और context कम हो, उनमें ऐसे documents को maintain करना क़ीमती होता है। लेकिन छोटे work projects में मैंने जितने भी developers द्वारा लिखे documents देखे हैं, वे आखिरकार unmanaged हो जाते हैं।

  • दस्तावेज़ जितना छोटा होगा, भविष्य के बदलावों से उसके invalid होने की संभावना उतनी कम होगी। यही ARCHITECTURE document का मुख्य नियम है — सिर्फ़ वही चीज़ें लिखो जिनके अक्सर बदलने की संभावना कम हो। इसे code के साथ sync करने की कोशिश मत करो।

    • Interfaces के बदलने की संभावना कम होती है और [ज़्यादा कठिन भी!] (Parnas, सिस्टम को modules में विभाजित करने के लिए इस्तेमाल किए जाने वाले मानदंड)।

  • हर project में onboarding के समय मैं architecture diagram और उसके components का छोटा सा explanation दिखाता हूँ।

    • अब मुझे हैरानी होती है कि open source में यह कितना दुर्लभ है।

  • यह बहुत उपयोगी practice है। कई projects में कुछ core files (या package/module/आदि) होते हैं जहाँ ज़्यादातर बदलाव होते हैं। अगर नए contributors (या लंबे समय बाद लौटे contributors) इन्हें जल्दी समझ सकें, तो project शुरू करने का समय काफ़ी कम किया जा सकता है।

  • मैं ऐसे छोटे document/code-based diagram standards का fan रहा हूँ:

    • README-driven development
    • ARCHITECTURE.md
    • ADRs
    • arc42
    • C4
    • वगैरह।
    • अब मैं git repository के /docs folder के अंदर एक Obsidian vault रखता हूँ।
    • किसी और के standard का इस्तेमाल करने के बजाय, मैं documentation को वैसे ही organize और refactor करता हूँ जैसे Obsidian में अपने personal notes को manage करता हूँ।
    • मैंने ऐसा common Markdown subset इस्तेमाल करने की कोशिश की जो GitHub(GFM) और Obsidian दोनों में काम करे, लेकिन आखिरकार मैंने यह छोड़ दिया और Obsidian के markdown और उसके dedicated features इस्तेमाल करने लगा।
    • Obsidian में Mermaid और LaTeX built-in हैं, और PlantUML के लिए plugin भी है।
    • visual figures/diagrams के लिए Canvas, DrawIO, Excalidraw built-in हैं।

  • उस समय चर्चा हुई थी:

    • Architecture.md - Feb 2021 (153 comments)