ARCHITECTURE.md (2021): प्रोजेक्ट संरचना तकनीकी विनिर्देश

 (matklad.github.io)
1 पॉइंट द्वारा GN⁺ 2024-02-26 | 1 टिप्पणियां | WhatsApp पर शेयर करें
  • 10k~200k लाइनों के open source प्रोजेक्ट्स में README, CONTRIBUTING के साथ ARCHITECTURE दस्तावेज़ रखने से नए contributors के लिए कोड संरचना समझने की लागत कम हो सकती है
  • किसी अपरिचित प्रोजेक्ट में patch लिखना लगभग 2 गुना धीमा होने से भी बड़ा मुद्दा यह है कि क्या और कहाँ बदलना है यह खोजने में 10 गुना ज़्यादा समय लग सकता है
  • यह दस्तावेज़ high-level संरचना और कम बदलने वाली बातों को संक्षेप में रखे, और कोड के साथ लगातार sync रखने के बजाय साल में कुछ बार इसकी समीक्षा करना अधिक उपयुक्त है
  • इसकी मुख्य संरचना समस्या का bird’s-eye view और codemap है, जो बड़े modules और उनके संबंध दिखाकर “X का काम करने वाला कोड कहाँ है” का उत्तर देनी चाहिए
  • महत्वपूर्ण नाम, architecture invariants, layers·system boundaries, और cross-cutting concerns दर्ज करें, लेकिन सीधे links की बजाय नाम से खोज को प्रोत्साहित करने से maintenance का बोझ कम होता है

ARCHITECTURE दस्तावेज़ लागत कैसे कम करता है

  • open source प्रोजेक्ट में कभी-कभार योगदान देने वाले व्यक्ति और core developer के बीच सबसे बड़ा अंतर यह है कि क्या वह प्रोजेक्ट की physical architecture जानता है
  • अपरिचित codebase में files को अक्सर ऐसे क्रम से पढ़ा जाता है जैसे वे बेतरतीब रखे गए तार्किक टुकड़े हों
  • जो developer पहले से सार्थक योगदान कर चुका है, उसके दिमाग में कोड का नक्शा होता है, इसलिए वह सीधे ज़रूरी जगह पर जा सकता है; और यदि वह नक्शा नहीं हो, तो वह संबंधित कोड को इधर-उधर खिसका भी सकता है
  • ARCHITECTURE फ़ाइल इस अंतर को कम लागत में घटाने का एक साधन है
  • दस्तावेज़ छोटा होना चाहिए
    • क्योंकि बार-बार योगदान करने वाले सभी लोगों को इसे पढ़ना चाहिए
    • और जितना छोटा होगा, भविष्य के बदलावों से उसके अमान्य होने की संभावना उतनी कम होगी
  • ARCHITECTURE में वही सामग्री होनी चाहिए जो अक्सर न बदलती हो
    • इसे कोड के साथ लगातार sync में रखने की कोशिश न करें
    • इसके बजाय साल में कुछ बार दोबारा समीक्षा करें

इसमें क्या होना चाहिए

  • पहले उस समस्या को bird’s-eye view स्तर पर व्यवस्थित करें जिसे प्रोजेक्ट हल करता है
  • इसके बाद कुछ विस्तार के साथ codemap लिखें
    • बड़े स्तर के modules और उनके आपसी संबंधों को समझाएँ
    • यह “X करने वाली चीज़ कहाँ है” का उत्तर देनी चाहिए
    • और “मैं जो अभी देख रहा हूँ, यह क्या करता है” इसका भी उत्तर देना चाहिए
  • हर module के अंदरूनी कामकाज में बहुत गहराई तक न जाएँ
    • ऐसी बातें अलग दस्तावेज़ में, या उससे भी बेहतर inline docs में रखी जा सकती हैं
    • codemap किसी देश का नक्शा है, किसी राज्य-स्तरीय atlas नहीं
  • codemap लिखने की प्रक्रिया में प्रोजेक्ट संरचना की भी जाँच की जा सकती है
    • codemap में जिन चीज़ों को आप पास-पास रखना चाहते हैं, वे tree . के परिणाम में भी एक-दूसरे के निकट हैं या नहीं, यह देखा जा सकता है
  • महत्वपूर्ण files, modules, और type names को स्पष्ट रूप से लिखें
    • सीधे links समय के साथ टूट सकते हैं, इसलिए उनसे बचें
    • इसके बजाय नाम के आधार पर symbol search की ओर मार्गदर्शन करने से maintenance बोझ बढ़े बिना संबंधित मिलते-जुलते नाम भी मिल सकते हैं
  • architecture invariants को स्पष्ट रूप से लिखना चाहिए
    • महत्वपूर्ण invariants अक्सर इस रूप में सामने आते हैं कि कोई चीज़ “मौजूद नहीं है”
    • उदाहरण के लिए web development में यह तथ्य कि model layer view पर निर्भर नहीं करती, केवल कोड पढ़कर समझना कठिन हो सकता है
  • layers और systems के बीच की boundaries भी दिखानी चाहिए
    • boundaries अपने पीछे मौजूद system implementation के बारे में संकेत देती हैं
    • और वे सभी संभावित implementations तक को सीमित करती हैं
    • अच्छी boundaries को कोड में यूँ ही खोज पाना कठिन होता है, इसलिए उनका documentation उपयोगी है
  • codemap के बाद cross-cutting concerns के लिए एक अलग section जोड़ें
  • देखने योग्य उदाहरण rust-analyzer के architecture.md में मिल सकता है

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

1 टिप्पणियां

 
GN⁺ 2024-02-26
Hacker News राय

  • मुझे यह आइडिया अच्छा लगता है, और repository के आकार से अलग, मुझे लगता है कि architecture explanation के लिए README में भी जगह होनी चाहिए
    उदाहरण के लिए, मुझे लगा कि सभी readers के लिए workflow को देखना और समझना ज़रूरी है, इसलिए मैंने main README में जानबूझकर Mermaid sequence diagram[1] डाला[2]
    [1] https://mermaid.js.org/syntax/sequenceDiagram.html
    [2] https://github.com/hbcondo/revenut-app?tab=readme-ov-file#-w...

    • natural language से Mermaid diagram बनाने वाला कोई tool हो तो काफ़ी शानदार होगा। सोचने लायक है

  • यह वाकई अच्छी सलाह जैसी लगती है
    चल रहे system की architecture को visualize करने वाले tools और बेहतर हों, यह चाहूंगा। यह अजीब है कि अभी भी code पढ़ना या Markdown file देखना ही latest तरीका है। किस्मत अच्छी हो तो Mermaid diagram मिल सकता है
    अच्छा होगा अगर architecture अपने-आप real time में सामने आए। macro scale की observability default रूप से built-in हो, ऐसा हो तो अच्छा होगा, और इससे हर कोई computing को बेहतर समझ पाएगा और मानवता को खुद को augment करने में भी मदद मिलेगी

    • dep-tree जैसी visualization में keyword search या LLM vector search जोड़ना अच्छा होगा। query करने पर संबंधित files और clusters highlight हो जाएं

  • ऐसे open source projects के लिए, जिनमें temporary contributors बहुत हैं, यह low-maintenance model के रूप में अच्छा लगता है। अगर project में dedicated engineers हैं, तो ADR पर भी विचार किया जा सकता है
    ADR में maintenance ज़्यादा चाहिए, लेकिन यह “ऐसा क्यों किया” और “किन alternatives पर विचार हुआ” छोड़ता है, इसलिए redesign करते समय बहुत उपयोगी होता है
    संदर्भ: https://adr.github.io/

    • यहां “बदले में” से ज़्यादा “साथ में” सही expression लगता है
      ARCHITECTURE.md current architecture state रखता है, और ADR उन decisions का record है जिनसे वहां तक पहुंचे। दोनों बहुत उपयोगी हैं
    • हमारी company में भी architects द्वारा लिखे बेकार documents हैं, और ज़्यादातर इसी तरह के हैं
      microservices, Kafka, Kubernetes: अभी users 4 हजार हैं, लेकिन अगर कभी 1 अरब हो गए तो क्या होगा—इस वजह से
      GraphDB: अगर SQL पर्याप्त न हुआ तो क्या होगा—इस वजह से
      ElasticSearch: अगर statistics के साथ full-text search भी करनी पड़ी तो क्या होगा—इस वजह से
      लेकिन ऐसे documents में से ज़्यादातर आखिरकार “मज़ेदार है इसलिए नई architecture/technology आज़माना चाहता हूं, FAANG में काम करने वाला colleague इसे इस्तेमाल करता है, मैंने वह book पढ़ी, resume पर अच्छा दिखेगा” का short form होते हैं
      जब वे अगला बड़ा project design करने आगे बढ़ जाते हैं, तो हमारी team को team members से भी ज़्यादा services और ऊपर वाले DB/technologies को लगातार sync में रखना पड़ता है। ज़ाहिर है, ऐसे problems को “बड़ा architecture decision” लेने की तुलना में कहीं ज़्यादा simple माना जाता है

  • अचानक ध्यान आया कि जितने भी IDE मैंने इस्तेमाल किए हैं, वे left side में project folder structure को standard directory tree के रूप में दिखाते हैं। क्या कोई IDE है जो project को dependency graph की तरह explore करने देता हो?

    • सवाल का direct जवाब नहीं है, लेकिन लगता है कि अंततः मतलब “file structure को बेहतर तरीके से visualize करना चाहता हूं” है
      मुझे नहीं लगता कि table-of-contents style representation ठीक बैठता है। आजकल coding workflow में terminal खोलता हूं, उसमें ranger चलाता हूं, और left-right directory structure explore करते समय उसी terminal में tab switch करता हूं। VSCode खोलकर split terminal में ऊपर normal terminal और नीचे Ranger चलाने जैसा। Midnight Commander भी चल सकता है, असल में कोई भी TUI file explorer ठीक है
      साथ ही project की architecture.md file में code map डालना शुरू किया है। tree -L चलाने पर Markdown में डालने लायक file structure tree diagram मनचाही depth तक मिल जाता है। उस output को Markdown में जोड़ता हूं, और हर file/folder के बाद 10 शब्दों से कम में उसका purpose बताने वाली comment लगाता हूं
      Ranger - https://github.com/ranger/ranger
      Midnight Commander - https://midnight-commander.org/
    • मैंने भी बिल्कुल यही सोचा था
      यह कैसा दिख सकता है, इसके लिए मेरे पास दो ideas हैं
      पहला, symbolic links इस्तेमाल करके files को orthogonal तरीके से organize करने वाले multiple directory trees। आम directory structure client/server में बंटता है, लेकिन अगर feature के आधार पर बांटना चाहें तो? IDE इसे बहुत आसानी से बना सकता है
      दूसरा, इस लेख की दिशा की तरह, IDE bookmarks बनाए और उनके बीच आना-जाना आसान करे ताकि लोगों को code समझाना आसान हो। कभी-कभी comment छोड़कर click करने पर codebase की किसी दूसरी जगह jump करना चाहता हूं। ऐसी चीज़ों को जोड़ दें तो पूरे codebase में फैली working को समझाने वाली narrative बुनी जा सकती है
      जानना चाहता हूं कि क्या कोई इस direction में काम कर रहा है
    • असल में यह कैसा होगा? उदाहरण के लिए circular dependencies को कैसे handle किया जा सकता है?
    • शायद आप multitree चाहते हों

  • मुझे लगता है कि यहां author जो कह रहा है उसे general software projects तक बहुत ज़्यादा expand करने में सावधानी रखनी चाहिए
    बहुत से context-less contributors वाले बड़े open source projects में ऐसे documents maintain करना काफ़ी valuable है। लेकिन छोटे work projects में, मैंने देखा है कि developers द्वारा commit किए गए documents आखिरकार सब unmaintained हो जाते हैं

    • मैंने teams के साथ कुछ बार architecture sessions किए हैं, और वे हमेशा valuable रहे हैं
      कम-से-कम यह पता चलता है कि team members के current architecture और ideal architecture को लेकर आपस में बहुत अलग-अलग विचार हैं। सिर्फ़ उसे explicitly सामने लाना ही document बनाने लायक है
      और “documents maintain नहीं होते” documents न बनाने की बहुत कमज़ोर वजह है। क्योंकि कोई भी document, चाहे पुराना हो या थोड़ा गलत, “कोई document नहीं” से बेहतर होता है

  • कुछ साल पहले अपने एक बड़े side project में मैंने मिलते-जुलते तरीके के साथ experiment किया था
    https://github.com/shipmight/shipmight/blob/master/src/ARCHI...
    हर file के ऊपर repository में मौजूद दूसरे ARCHITECTURE.md files तक जाने वाला link tree रखा था। उदाहरण इस तरह है: ARCHITECTURE.md <- मौजूदा जगह, backend/ARCHITECTURE.md, backend/api/ARCHITECTURE.md, backend/cli/ARCHITECTURE.md, backend/ui/ARCHITECTURE.md, backend/utils/ARCHITECTURE.md, frontend/ARCHITECTURE.md, internal-charts/ARCHITECTURE.md

    • हर package/module/top-level directory में README.md रखने पर GitHub UI उसे file list के नीचे render कर देता है
      यह ऐसी जगहों पर दिखता है: https://github.com/shipmight/shipmight/tree/master/src/backe...
      कुछ projects में भी मैंने यह तरीका देखा है

  • जितना छोटा होगा, future changes से invalid होने की संभावना उतनी कम होगी। ARCHITECTURE का मुख्य rule of thumb यह है कि सिर्फ वही लिखें जो बार-बार बदलने वाला नहीं है। इसे code के साथ sync करने की कोशिश नहीं करनी चाहिए
    Interfaces के बदलने की संभावना कम होती है, और उन्हें बदलना भी ज्यादा कठिन होता है। यह systems को modules में split करने के criteria पर Parnas का नजरिया है
    मैं सहमत हूँ कि codebase को समझना मुश्किल होता है। “Patterns” के नाम देना कुछ हद तक मदद करता है, लेकिन आखिर में काफी पढ़ना ही पड़ता है
    GitHub में file-level commit messages अक्सर explanation जैसे लगते हैं। क्या वह शायद ज्यादा उपयोगी हो सकता है?

  • जिन भी projects में मैंने काम किया, उनमें onboarding के समय architecture diagram और components का छोटा description मिला
    इसलिए हैरानी होती है कि open source में यह इतना common नहीं है

    • “Components का description” ही असली समस्या है। क्योंकि किसी को यह करना पड़ता है
      Open source projects में किसी employee का पहला working day नहीं होता, इसलिए ऐसी introduction भी नहीं होती
      अगर बहुत ज्यादा समय न हो, तो ऐसे descriptions खास अच्छे नहीं होते। Employees से उम्मीद की जाती है कि वे अकेले कुछ कर पाने में कुछ हफ्ते लगाएंगे, लेकिन security consultants के रूप में हमें हर 2 हफ्ते में बिल्कुल नई explanation सुननी पड़ती है। समस्या यह है कि ये explanations improvisational और unstructured होती हैं, और बोलने वाला व्यक्ति curse of knowledge की वजह से बहुत सारी गैर-जरूरी details बता देता है
      शायद repository में नया आया व्यक्ति एक बार इसे लिख दे, और बाद में बस maintain किया जाए, यह बेहतर होगा। दूसरा अच्छा विकल्प यह है कि कोई भी हर बार improvisation में समझाने के बजाय, क्या शामिल करना है और क्या छोड़ना है, इस पर करीब 1 मिनट सोचकर उसे लिख दे। जैसा लेखक ने कहा, इस file को project की high-level architecture समझानी चाहिए और छोटा होना चाहिए। Repeat contributors को इसे जरूर पढ़ना चाहिए, और जितना छोटा होगा, future changes से invalid होने की संभावना भी उतनी कम होगी

  • मुझे यह हमेशा बहुत उपयोगी practice लगी है। कई projects में कुछ core files, या packages/modules आदि होते हैं, जहाँ ज्यादातर changes होते हैं
    अगर नए contributors या लंबे समय बाद लौटे contributors उन्हें जल्दी समझ सकें, तो project शुरू करने का समय काफी घट जाता है
    कई workplaces में मैंने projects में architecture file जोड़ी है और [0], [1] response अच्छा रहा। Perfect नहीं है, लेकिन न होने से बेहतर है
    [0]: https://github.com/zapier/zapier-platform/pull/324
    [1]: https://github.com/stripe/stripe-cli/blob/master/ARCHITECTUR...

    • क्या GitHub में ऐसी चीज automatically देखने का कोई तरीका है? जैसे file change heatmap

  • पहले मुझे ऐसे छोटे docs/diagrams-as-code standards बहुत पसंद थे
    जैसे README-driven development, ARCHITECTURE.md, ADR, arc42, C4 वगैरह
    अब मैं बस git repository के /docs folder में Obsidian vault रखता हूँ
    दूसरों के standards इस्तेमाल करने के बजाय, Obsidian में personal notes manage करने की तरह docs को लगातार organize और refactor करता हूँ
    शुरुआत में मैं GitHub के GFM और Obsidian दोनों में काम करने वाला common Markdown subset इस्तेमाल करना चाहता था, लेकिन छोड़ दिया; अब Dataview plugin और templates जैसी proprietary features सहित Obsidian-style Markdown को वैसे ही इस्तेमाल करता हूँ
    Mermaid और LaTeX Obsidian में built-in हैं, और PlantUML plugin भी है। Visual pictures/diagrams के लिए built-in Canvas, DrawIO, Excalidraw इस्तेमाल करता हूँ