Go में दस्तावेज़ीकरण: कोड जो खुद बोले, सीखें आसानी से

Go में दस्तावेज़ीकरण क्यों एक सुपरपावर है, न कि एक उबाऊ काम

कल्पना करें: आप किसी और का Go प्रोजेक्ट खोलते हैं, और वहाँ एक भी कमेंट नहीं है। फंक्शन का नाम f1, f2 है, और स्ट्रक्चर का नाम Data और MoreData है। परिचित लग रहा है? अगर हाँ, तो आप जानते हैं कि कैसे उत्साह जल्दी ही रिपॉजिटरी को बंद करने की इच्छा में बदल जाता है।

Go एक ऐसी भाषा है जो सादगी और स्पष्टता से प्यार करती है। लेकिन सबसे साफ कोड भी हमेशा खुद नहीं बोलता। Go में अच्छा दस्तावेज़ीकरण सिर्फ सहकर्मियों के लिए एक "अच्छा इशारा" नहीं है। यह एक पेशेवर उपकरण है जो:

\n
• नए डेवलपर्स को ऑनबोर्ड करने की प्रक्रिया को तेज़ करता है;
\n
• बग्स से बचने में मदद करता है (क्या आपको याद है कि कमेंट्स API के गलत उपयोग से बचा सकते हैं?);
\n
• pkg.go.dev पर स्वचालित रूप से सुंदर पेज जनरेट करता है;
\n
• कोड की गुणवत्ता बढ़ाता है (एक खराब फंक्शन पर कमेंट लिखने की कोशिश करें — आप खुद इसे फिर से लिखना चाहेंगे)।
\n

इस लेख में, हम Go प्रोजेक्ट्स को डॉक्यूमेंट करने की बेस्ट प्रैक्टिसेज पर चर्चा करेंगे। godoc के बुनियादी नियमों से लेकर रियल उदाहरणों तक, जिन्हें आप आज ही लागू कर सकते हैं। चलिए शुरू करते हैं!

Go में दस्तावेज़ीकरण का दर्शन: कम शब्द, ज़्यादा अर्थ

Go Java या Python नहीं है। यहाँ कोई बहु-पृष्ठ Javadoc या 20 लाइनों के docstrings नहीं लिखता। Go का दर्शन सरल है: व्यवहार का दस्तावेज़ीकरण करें, कार्यान्वयन का नहीं।

आधिकारिक गाइड Effective Go में स्पष्ट रूप से कहा गया है: कमेंट्स को यह बताना चाहिए कि कोड क्या करता है, न कि कैसे करता है। अगर आपका कोड इतना जटिल है कि एल्गोरिदम समझाने के बिना काम नहीं चलता, तो शायद इसे सरल बनाने की ज़रूरत है।

मुख्य सिद्धांत:

\n
• कमेंट एक वाक्य है। फंक्शन या टाइप के नाम से शुरू करें। // Calculate returns the result of the calculation. — बढ़िया। // This function calculates... — फोकस खो देता है।
\n
• अंग्रेज़ी में लिखें। Go एक अंतरराष्ट्रीय भाषा है, और अंग्रेज़ी में दस्तावेज़ीकरण डी-फैक्टो मानक है। लेकिन अगर आपका प्रोजेक्ट सिर्फ हिंदी भाषी टीम के लिए है, तो हिंदी में भी लिख सकते हैं। मुख्य बात एकरूपता है।
\n
• स्पष्ट चीज़ों को न समझाएँ। // SetName sets the name — बेकार है। बेहतर: // SetName updates the user's display name. Must be called before Save.
\n

Godoc: आपका सबसे अच्छा दोस्त और ऑटोमैटिक डॉक्यूमेंटेशन जनरेटर

Go एक बिल्ट-इन टूल godoc के साथ आता है। यह सीधे कोड से कमेंट्स पार्स करता है और HTML दस्तावेज़ीकरण बनाता है। इसका मतलब है कि आपका दस्तावेज़ीकरण कोड के साथ रहता है — और एक साथ अपडेट होता है।

यह कैसे काम करता है? बहुत आसान। एक्सपोर्ट की गई एंटिटी (फंक्शन, टाइप, स्ट्रक्चर, कॉन्स्टेंट) के ठीक पहले एक कमेंट लिखें — और godoc इसे अपने आप ले लेगा।

बेसिक पैकेज का उदाहरण:

// Package calculator provides basic arithmetic operations.\npackage calculator\n\n// Add returns the sum of two integers.\nfunc Add(a, b int) int {\n    return a + b\n}\n\n// Subtract returns the difference of two integers.\nfunc Subtract(a, b int) int {\n    return a - b\n}

अब godoc -http :8080 चलाएँ और ब्राउज़र खोलें। आपको पैकेज और हर फंक्शन के विवरण के साथ एक सुंदर पेज दिखाई देगा। जादू!

godoc के लिए अच्छे व्यवहार के नियम

\n
• हमेशा पैकेज पर कमेंट करें। पैकेज कमेंट वह पहली चीज़ है जो उपयोगकर्ता देखता है। इसे पैकेज के उद्देश्य का वर्णन करना चाहिए, और आदर्श रूप से इसमें उपयोग का एक उदाहरण होना चाहिए।
\n
• टाइप और स्ट्रक्चर को न भूलें। अगर स्ट्रक्चर में ऐसे फील्ड हैं जो नाम से स्पष्ट नहीं हैं, तो उन्हें भी डॉक्यूमेंट करें।
\n
• खाली लाइन का उपयोग करें। godoc पहले पैराग्राफ को संक्षिप्त विवरण के रूप में और बाकी को विस्तार के रूप में लेता है। उन्हें खाली लाइन से अलग करें।
\n

// User represents a user in the system.\n// It contains the user's ID, name, and email.\ntype User struct {\n    ID    int\n    Name  string\n    Email string\n}