अच्छे code comments लिखने की गाइड

• code comments की भूमिका:

  • code comments सिर्फ ‘आपके लिखे code क्या करता है’ यह समझाने से आगे बढ़कर design decisions, trade-offs और अन्य विचारों को document करते हैं
  • इससे यह समझाने में मदद मिलती है कि ‘code लिखने वाले ने क्या किया और ऐसा क्यों किया’
  • code comments, code लिखने की पिछली प्रक्रिया में लिए गए निर्णयों का context साझा करने में मदद करते हैं
  • यह ऐसी code information पहुंचाते हैं जिन्हें सिर्फ code के जरिए व्यक्त करना मुश्किल होता है

• code comments का महत्व:

  • complex code के पहले लिखा inline code comment, बाद में code देखने वाले दूसरे developers का समय बचाता है
  • project जितना विकसित होता है, पहले लिए गए code decisions का context छोड़ना उतना ही जरूरी होता है ताकि दूसरे developers को मदद मिल सके
  • अगर code complex है, तो उसके पहले कम से कम एक पंक्ति का inline code comment होना चाहिए
  • सिर्फ code के जरिए code decisions के context सहित कई तरह की जानकारी पहुंचाने की सीमाएं होती हैं

• अच्छे code comments लिखने के तरीके:

  1. संक्षेप में लिखें
     • सिर्फ जरूरी होने पर, अनिवार्य जानकारी शामिल करके comment लिखें
       • जब code का complex होना अपरिहार्य हो
       • जब precision बढ़ाने के लिए details जोड़नी हों
       • जब context गायब हो (उदाहरण: किसी दूसरे repository या package का code इस्तेमाल करते समय)
     • comments में भ्रम और अस्पष्टता कम करें, और उपयोगी context व जानकारी दें
  2. TODOs/FIXMEs comments का उपयोग करें
     • TODOs/FIXMEs comments यह दिखाने का तरीका हैं कि ‘code के किसी खास हिस्से का काम अभी पूरा नहीं हुआ है या उसमें सुधार की जरूरत है’
     • function के पहले “TODO: XX feature जोड़ना है” जैसे रूप में लिखें
     • code लिखते समय अगर लगे कि 'इस हिस्से को बाद में फिर देखना होगा' या 'यह feature आगे चलकर develop करना है', तो इस तरीके से संबंधित बातों को रिकॉर्ड और track किया जा सकता है
     • उपयोगी Extension: TODO Highlight
  3. comments से code का बचाव न करें
     • गलत और अस्पष्ट code पर comments लिखकर सफाई देने से बेहतर है कि code को फिर से लिखा जाए
     • कुछ code को comments से समझाना जरूरी होता है, लेकिन कुछ code को comments पर निर्भर हुए बिना ‘अपने आप’ बोलना चाहिए
  4. AI का उपयोग करें
     • AI comment generator का उपयोग करने पर किसी खास standard के अनुसार एक समान format में comments बनाए जा सकते हैं
     • पूरे project में comments की consistency बनाए रखी जा सकती है, जिससे code की readability बेहतर होती है
     • उपयोगी AI comment generator: Readable

[penza1]

अगर लगे कि comment की ज़रूरत है,
तो क्या यह सोचकर देखना ठीक नहीं होगा कि कहीं code ही गलत तो नहीं है?

ऐसे comments जो code के lifecycle और functionality के साथ-साथ नहीं चलते, भविष्य में उस comment को देखने वाले developer या ख़ुद मुझे भी भ्रमित कर सकते हैं।

भले ही अतीत का context अब वर्तमान से असंबंधित हो गया हो या error पैदा कर चुका हो,
फिर भी उसी पुराने context वाले वाक्य की वजह से मौजूदा बदलाव करने में हिचकिचाहट हो सकती है, या किसी दूसरी संरचना में हल करने के बजाय घुमाकर workaround किया जा सकता है,
और इससे ज़्यादा गलतियाँ भी हो सकती हैं..

मेरे अनुभव में, ऐसे comments बहुत कम होते हैं जो यह समझा सकें कि जो बात तब सही थी, वह अब गलत क्यों है....

[ironlung]

कीमती राय साझा करने के लिए धन्यवाद। आपकी बातों पर सोचकर लगा कि कोड के विकास के लिए भी यह ज़रूरी है कि हम टिप्पणियों की आवश्यकता पर बारीकी से बार-बार सवाल करें। :)

[aqqnucs]

https://youtu.be/Bf7vDBBOBUA?si=0-v44x48-rlVsYCq

इसे देखते हुए मैं भी यह कोशिश करता/करती हूँ कि comments ज़रूरत से ज़्यादा न लिखूँ

[ironlung]

अच्छा वीडियो शेयर करने के लिए धन्यवाद! :)

[iamchanii]

सड़कें चाहे कितनी भी अच्छी तरह बनी हों, मुझे लगता है कि संकेतक फिर भी ज़रूरी होते हैं। इसलिए इन दिनों मैं comments लिखने की आदत डालने की कोशिश कर रहा हूँ।

[ironlung]

अपनी insightful टिप्पणी साझा करने के लिए धन्यवाद। आपकी बात पर सोचते हुए लगा कि comments भी technical writing का एक महत्वपूर्ण हिस्सा हैं, इसलिए writing के बुनियादी principles को फिर से देखने का मन हुआ। :)

[balak]

मुझे लगता है कि सबसे अच्छा तरीका यह है कि कोड ऐसा लिखा जाए जिसे बिना किसी comment के भी समझा जा सके।

[ironlung]

जी, मुझे भी लगता है कि सबसे पहले बुनियादी बातों पर ठीक से ध्यान देना ज़रूरी है। टिप्पणी के लिए धन्यवाद। :)