Why Not Comments

 (buttondown.com)
3 पॉइंट द्वारा GN⁺ 2024-09-12 | 1 टिप्पणियां | WhatsApp पर शेयर करें
  • "why not" comments क्यों नहीं? यह "comments क्यों नहीं" नहीं है
    • “आप यह क्यों नहीं लिखते कि ‘यह क्यों काम नहीं किया’? सवाल यह नहीं है कि ‘आपने comment क्यों नहीं लिखा’।”

Why Not Comments

  • code एक structured machine language में लिखा जाता है, और comments अधिक अभिव्यंजक human language में लिखे जाते हैं
  • इसका मतलब है कि "क्या" को comment में लिखने के बजाय, जितनी हो सके उतनी जानकारी identifiers में शामिल करें
  • हाल के समय में कुछ लोग यह भी तर्क देते हैं कि "क्यों" भी comments में नहीं होना चाहिए, बल्कि LongFunctionNames या test case के नामों में शामिल होना चाहिए
  • "self-documenting" codebase identifiers के ज़रिए documentation जोड़ता है

हाल का उदाहरण

  • Logic for Programmers से लिया गया उदाहरण
  • epub build में math symbols (\forall) को symbol (∀) में convert न कर पाने की समस्या हुई
  • math strings के tokens को Unicode से manually replace करने वाला एक script लिखा गया
  • इसे 16 math symbols को अलग-अलग replace करने के तरीके से लिखा गया, लेकिन यह inefficient है
  • एक simple comment जोड़कर इसे हल किया गया
    • "यह हर string के लिए 16 बार iterate करता है, लेकिन अभी किताब में सिर्फ 25 math strings हैं और उनमें से ज़्यादातर 5 characters से कम हैं, इसलिए यह अभी भी काफ़ी fast है"

comments क्यों लिखने चाहिए

  • slow code तुरंत समस्या न भी पैदा करे, फिर भी comments लिखने की वजह है
  • भविष्य में यही code समस्या बन सकता है
  • comments दिखाते हैं कि आप trade-off को समझते थे
  • बाद में project को फिर देखने पर यह समझा जा सकता है कि slow code क्यों लिखा गया था

self-documenting क्यों संभव नहीं है

  • RunFewerTimesSlowerAndSimplerAlgorithmAfterConsideringTradeOffs जैसे लंबे function names trade-off को समझाते नहीं हैं
  • function और variable identifiers में केवल एक प्रकार की information समा सकती है
  • comments को tests से replace करना भी संभव नहीं है
  • self-documenting यह बताता है कि code क्या करता है, लेकिन negative information यह बताती है कि code क्या नहीं करता

newsletter के अंत की अटकल

  • यह सोचने की बात है कि क्या "क्यों नहीं" comments को counterfactual cases की तरह देखा जा सकता है
  • क्या human communication की abstraction self-documenting नहीं हो सकती?
  • क्या metaphor, uncertainty, ethical arguments आदि को self-documenting बनाया जा सकता है?

GN⁺ का सार

  • यह लेख code comments के महत्व और उनकी सीमाओं पर चर्चा करता है
  • comments के माध्यम से code के trade-off को स्पष्ट किया जा सकता है और future maintenance आसान होती है
  • यह self-documenting की सीमाओं और comments की आवश्यकता पर ज़ोर देता है

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

1 टिप्पणियां

 
GN⁺ 2024-09-12
Hacker News की राय

  • कोड में comments लिखते समय, मुख्य रूप से "क्यों" और "क्यों नहीं किया जा सकता" समझाया जाता है। जटिल कोड के मामले में "क्या" को संक्षेप में समझाना भी उपयोगी होता है

    • अनिवार्य comments अप्रभावी होते हैं, और हर function पर comment लिखना समय की बर्बादी है
    • tools द्वारा अपने-आप जोड़े गए comments भी अप्रभावी होते हैं

  • जूनियर engineer ऐसे comments लिखते हैं जो बताते हैं कि कोड क्या करता है, mid-level engineer बताते हैं कि इसे इस तरह क्यों लिखा गया, और senior engineer बताते हैं कि इसे किसी और तरीके से क्यों नहीं लिखा गया

  • maintainers के लिए comment template इस्तेमाल किया जाता है

    • "यह कोड <कारण> की वजह से इस तरह लिखा गया है। अगर आप इसे बदलने की कोशिश करें और बाद में समझें कि यह गलती थी, तो अगले व्यक्ति के लिए counter बढ़ा दें: total_hours_wasted_here = n"

  • कोड के surprising हिस्सों पर comment करना महत्वपूर्ण है

    • जब यह भरोसा न हो कि बाद में कोड समझ में आएगा, तब "क्यों नहीं किया जा सकता" समझाने वाला comment लिखा जाता है

  • comments के महत्व पर ज़ोर दिया गया, खासकर तब जब आपको अपना ही कोड 5, 10, 15 साल बाद भी maintain करना हो

    • मौजूदा कोड के साथ consistency बनाए रखना महत्वपूर्ण है

  • "जो naive solution नहीं है" उस पर comment करना अच्छा होता है

    • अप्रभावी कोड को बाद में बदला जाए तो वह समस्या पैदा कर सकता है

  • लंबे function names या test case names में comment का आशय शामिल करना अच्छा होता है

    • जब method name पर्याप्त स्पष्ट न हो, तब comment मददगार होता है
    • अगर method description में "और" शामिल है, तो यह संकेत है कि method बहुत ज़्यादा काम कर रहा है

  • debug logging के ज़रिए यह चेतावनी जोड़ना भी उपयोगी है कि input मूल design constraints से बड़ा है

  • comments और doc comments का ज़्यादा उपयोग करना पसंद किया जाता है

    • application के हर चरण के लिए comment लिखे जाते हैं, और कोड लिखते समय comments को और सूक्ष्म बनाया जाता है
    • हर function और variable पर comment लिखना पसंद किया जाता है

  • code review में संभावित आलोचना से पहले ही बचने के लिए "X नहीं किया क्योंकि Y" जैसा comment लिखा जाता है