कृपया code की व्याख्या सरल रखें

• code review में जब लंबी व्याख्या और बड़ा diff साथ आते हैं, तो reviewer के लिए बदलाव के कारण को समझना मुश्किल हो जाता है, इसलिए commit message, merge request description, और comments संक्षिप्त होने चाहिए
• व्याख्या का फोकस क्या बदला है से ज़्यादा क्यों बदला है पर होना चाहिए, क्योंकि कई बदलाव code से ही देखे जा सकते हैं
• एक ही बार में पूरा context भर देने वाली लंबी व्याख्या कुछ reviewers की एकाग्रता और review की गति को कम कर सकती है
• merge review में atomic commits खास तौर पर महत्वपूर्ण हैं, और छोटे सुधार git amend से किए जा सकते हैं; merge से पहले cleanup rebase या squash से किया जा सकता है
• LLM tools का उपयोग करने पर भी comments, descriptions, और commit messages खुद लिखना code की समझ और review accessibility के लिए अधिक मददगार होता है

---

review की व्याख्या में “क्या” से ज़्यादा “क्यों” पर फोकस करें

• code review में अगर descriptions, commits, और merge requests अत्यधिक जानकारी से भरे हों, तो review का बोझ बढ़ जाता है
• बदलावों की लंबी सूची लिखने के बजाय, मुख्य बात यह है कि बदलाव क्यों किया गया यह स्पष्ट लिखा जाए
• code स्वयं अधिकांश बदलाव दिखा सकता है, और जो context कम हो उसे reviewer सवाल करके समझ सकता है
• निबंध की तरह लिखी गई लंबी व्याख्या, ध्यान केंद्रित करने में कठिनाई महसूस करने वाले लोगों के लिए review को और धीमा बना सकती है
• commit messages, merge request descriptions, और code comments स्पष्ट, बिंदुवार, और केवल आवश्यक जानकारी वाले होने चाहिए

commit व्यवस्थित करने और LLM उपयोग पर अनुरोध

• merge review में commits खास तौर पर atomic होने चाहिए, और हर बदलाव को स्वतंत्र रूप से समझा जा सकना चाहिए
• छोटे सुधार git amend से शामिल करें, और merge से पहले rebase करके व्यवस्थित करें या squash कर सकते हैं
• LLM tools का उपयोग करने पर भी comments, descriptions, और commit messages खुद लिखना बेहतर माना गया है
  • खुद लिखने की प्रक्रिया बदलावों को समझने में मदद करती है
  • खुद लिखी गई व्याख्या reviewer के लिए अधिक सुलभ हो सकती है
• यह व्यक्तिगत राय भी शामिल है कि संभव हो तो LLM tools से बचना बेहतर है
• accessibility शब्द पर प्रतिक्रिया आई थी, लेकिन मुख्य आग्रह यही है कि code review की व्याख्या अधिक संक्षिप्त और review के लिए आसान बनाई जाए

[GN⁺]

Lobste.rs टिप्पणियाँ

• accessibility की ज़रूरतों को किसी खास व्यक्ति की पसंद के बराबर मान लेने में सावधानी बरतनी चाहिए
  किसी के पास ADHD होने का यह मतलब नहीं कि लंबे commit message पसंद न करना ADHD की सार्वभौमिक विशेषता है, और accessibility का मतलब “ADHD वाले व्यक्ति को जो पसंद है वह सब कर देना” नहीं, बल्कि आम उपयोगकर्ताओं पर ज़रूरत से ज़्यादा बोझ डाले बिना उचित समायोजन करना है
  इसलिए high contrast, reduced motion, dark mode जैसी कई accessibility सुविधाएँ ऐसी settings के पीछे रखी जाती हैं जिन्हें व्यक्ति खुद चुन सके

  • इसे मैं और स्पष्ट लिख सकता था, लेकिन मेरे AuDHD को ठीक से काम करने और कार्य करने के लिए कुछ खास शर्तें चाहिए
    लंबे text blocks, जैसे किसी छोटे बदलाव के साथ A4 के दो पन्नों जितनी व्याख्या जुड़ जाना, मेरे काम को पूरी तरह रोक सकता है, और उसे ज़बरदस्ती पढ़ने की कोशिश burnout तक ले जा सकती है
    शायद मुझे इसे “यह मेरी accessibility ज़रूरत है, और मुझे पता है कि मेरे जैसे और भी बहुत लोग हैं” की तरह कहना चाहिए
    फिर भी इसे ज़रूरत की बजाय पसंद माना जा सकता है, लेकिन जब commit message में LLM द्वारा बनाई गई text wall चिपकाई जाए तो कृपया मेरे जैसे लोगों को भी ध्यान में रखें
  • यह हर व्यक्ति में अलग हो सकता है, लेकिन “पहले मुख्य बात बताइए” को मैं ADHD की काफ़ी मूलभूत विशेषताओं में से एक मानता हूँ
    accessibility के लिहाज़ से भी इस तरह के समायोजन का लाभ सबको मिलता है, इसलिए इसका विरोध करने की कोई खास वजह नहीं दिखती
  • मेरे अनुभव में neurodivergent और disabled लोगों को होने वाली अनावश्यक कठिनाइयों का बड़ा हिस्सा accessibility की ज़रूरतों को महज़ पसंद समझ लेने से पैदा होता है
    accessibility बढ़ने पर उन लोगों को भी लाभ मिलता है जिन्हें बराबर शुरुआती स्थिति पाने के लिए इसकी सख्त ज़रूरत नहीं होती, इसलिए उस दिशा में जाना अच्छा है

• AI से पहले से ही मैं हमेशा ज़रूरत से ज़्यादा विस्तृत comments को पसंद करता रहा हूँ, और जिन लोगों के साथ मैंने काम किया उनमें से कई इस पर हैरान भी हुए
  उदाहरण के लिए यह method है: https://github.com/ghostty-org/ghostty/…
  पिछले 15 सालों से, भाषा चाहे कोई भी रही हो, मैं मोटे तौर पर इसी शैली में लिखता आया हूँ, और AI युग में मैंने यह तरीका AGENTS.md में भी साफ़ लिखा है
  लिंक की गई file और comments सब इंसानों ने लिखे हैं, AI का बिल्कुल उपयोग नहीं हुआ
  वजह सीधी है: यह comments और code के बीच double-entry rule लागू करता है
  अगर दोनों मेल नहीं खाते, तो comment ग़लत है, या code ग़लत है, या दोनों ग़लत हैं; और सिर्फ़ “इनमें सही कौन है?” पूछने से ही बहुत सी समस्याएँ पकड़ में आई हैं
  आखिरकार, अगर यह आपका अपना project है तो comments कैसे लिखने हैं यह हर किसी की अपनी पसंद हो सकती है

  • मुझे भी कभी-कभी मज़ाक में कहा जाता है कि मैं code से ज़्यादा comments लिखता हूँ, और सच कहूँ तो मुझे ऐसे comments बहुत पसंद हैं
    बाद में code दोबारा पढ़ते समय ये उस समय लिए गए स्थानीय निर्णयों का संदर्भ संभालकर रखते हैं, और reviewer या पहली बार देखने वाले व्यक्ति को भी संदर्भ बनाने में मदद करते हैं
    ऐसे comments लंबे ज़रूर होते हैं, लेकिन लेख में जिन “अनावश्यक विवरणों” की बात है वे नहीं हैं; साझा किया गया उदाहरण “क्या नहीं, क्यों समझाओ” वाली कहावत का अच्छा उदाहरण लगता है
  • ऐसे comments शानदार हैं
    उदाहरण की तरह, macOS उपयोगकर्ता ~/.bash_profile में shell configuration क्यों रखते हैं और login shell की उम्मीद क्यों करते हैं, यह समझाने वाले comments किसी खास निर्णय के पीछे का उपयोगी संदर्भ देते हैं
    लेकिन LLM पर लौटें तो, निजी तौर पर मैंने अभी तक उस गुणवत्ता के LLM-generated comments नहीं देखे
    ज़्यादातर वे बस इतना दोहराते हैं कि foo() करता है, फिर bar() करता है, और आख़िर में baz करता है — यानी वही बातें जो code पढ़कर पहले से स्पष्ट हैं
  • लिंक में दिए गए तरह के comments में कोई समस्या नहीं है
    समस्या तब है जब बहुत छोटे बदलावों के साथ भी विशाल tables और bullet listों का तमाशा जोड़ दिया जाता है
  • उस स्तर की विस्तारप्रियता के लिए मैं सचमुच आभारी हूँ, लेकिन निजी तौर पर मैं चाहूँगा कि यह comment की बजाय उस method को जोड़ने वाले commit की commit message में हो
    commit message code के साथ उसी समय का रिकॉर्ड बनकर रहती है, जबकि comments समय के साथ बेमेल हो सकते हैं
  • 1467वीं पंक्ति से शुरू होने वाला comment तो कमाल का है, उसमें थकान साफ़ महसूस होती है

• दफ़्तर में मैंने PR template में विनम्रता से यह लिखकर देखा कि “कृपया इस बदलाव की प्रेरणा और review के दौरान देखने लायक महत्वपूर्ण design decisions सीधे समझाएँ”
  लेकिन 10 में से 9 बार उस समय जो भी LLM इस्तेमाल हो रहा होता है, वह पूरा template उड़ा देता है और जोड़े गए tests की संख्या, pass checkbox, और मामूली बातों पर लंबी शाखाएँ निकालते हुए एक लंबा विवरण उगल देता है
  इससे review करना कितना आनंददायक हो जाता है

  • दफ़्तर में हमारे यहाँ भी यही समस्या है
    किसने सोचा कि LLM-generated commit message tools को हर जगह जोड़ देना अच्छा विचार है, पता नहीं, लेकिन नतीजा यह होता है कि commits के अंदर https://noslopgrenade.com/ जैसी समस्या आ जाती है
    commit message या pull request description में बदलाव की वजह, design decisions, rationale जैसे उपयोगी संदर्भ नहीं रहते, और उनकी जगह ऐसी पैराग्राफ़नुमा बातें आ जाती हैं जो code पढ़कर पहले से समझी जा सकती हैं
  • मैंने भी यही व्यवहार देखा है
    मैं agents.md में यह जोड़ने पर विचार कर रहा हूँ कि “commit message लिखते समय commit-messages.md देखें”
    commit-messages.md में pass/fail test checkbox पर रोक, अलग-अलग tests की सूची देने की बजाय उनका सार लिखना या बिल्कुल न लिखना जैसी commit message guidelines रखी जा सकती हैं

• मैं जो कर रहा हूँ उसे comment में तब ही लिखता हूँ जब मुझे यह भरोसा न हो कि मैं यह क्यों कर रहा हूँ, बल्कि यह कि यह तरीका सही है या नहीं
  बार-बार पीड़ा देने वाली सबसे बड़ी वजह regular expressions हैं

  • मैं भी यही करता हूँ
    कभी-कभी हर चीज़ को ठोस तरीके से समझाना पड़ता है, लेकिन आजकल variables के नाम बदलने जैसे छोटे बदलावों पर भी विशाल व्याख्याएँ जुड़ी मिलती हैं

• दिलचस्प बात यह है कि मुझे तो उल्टा अक्सर कहा गया है कि मेरी commit messages बहुत छोटी होती हैं

  • इस लेख की चर्चा दूसरी दिशा में है, यानी उन लोगों की शिकायत के समानांतर कि व्याख्या बहुत छोटी है, जैसा Chesterton middle finger वाले लेख में है
  • बहुत छोटी होना भी समस्या हो सकती है, लेकिन उसमें पूरा उपन्यास भर देना भी बेतुका है
  • LLM सच में बहुत ज़्यादा लिखते हैं
    इसलिए मैंने claude को comments कभी न लिखने के लिए सेट कर दिया, क्योंकि मैं बाद में हाथ से 98% मिटा रहा था और बचे हुए 2% को भी फिर से लिख रहा था

• आम तौर पर मुझे बहुत विस्तार से लिखे गए commit messages पसंद हैं, लेकिन मैं समाचार-लेख जैसी संरचना को प्राथमिकता देता हूँ, जहाँ सबसे महत्वपूर्ण जानकारी पहले आती है और कम महत्वपूर्ण लेकिन फिर भी प्रासंगिक विवरण बाद में रखे जाते हैं
  उदाहरण के लिए, शीर्षक में सबसे महत्वपूर्ण जानकारी को यथासंभव सघन रूप में रखा जाए, पहले पैराग्राफ में बदलाव को थोड़ा कम संक्षिप्त वाक्यों में समझाया जाए, और बाद के पैराग्राफ में ऐसे अतिरिक्त विवरण हों जिन्हें तब तक ध्यान से पढ़ने की ज़रूरत न पड़े जब तक code change की प्रकृति को समझना सच में कठिन न हो
  मुझे लगता है कि बाद में code पढ़ने वाले लोगों के लिए commit message कितना महत्वपूर्ण होता है, इसका अक्सर कम आकलन किया जाता है
  जब आप codebase में गहराई से जाते हुए यह जानना चाहें कि कोई block ऐसा क्यों दिखता है, और git blame आपको ऐसे commit message तक ले जाए जो बहुत विस्तार से समझाता हो कि जो तरीका बेढंगा लग रहा था वह वास्तव में कई बेहतर दिखने वाले लेकिन अधूरे तरीकों के बाद बचा हुआ विकल्प था, तो यह कभी निराशाजनक नहीं लगता
  लेखक की मुख्य बात पर लौटें तो, संचार में स्पष्ट संकेत जोड़ना अच्छा समायोजन है और सामान्य रूप से भी उपयोगी है
  commit message के बीच में आप ऐसा वाक्य जोड़ सकते हैं जैसे, “अगर आप इस code का review कर रहे हैं, तो यहाँ पढ़ना बंद कर सकते हैं”

• “अनावश्यक विवरण ज़रूरत होने पर पूछे जा सकते हैं” कहना यह काफी साहसिक मान लेना है कि वह व्यक्ति आगे भी आसपास रहेगा
  10 साल से अधिक पुराने FLOSS codebase में योगदान देना शुरू करने के बाद मैंने commit messages मेहनत से लिखने शुरू किए
  code वैसा क्यों मौजूद है, यह पता लगाने का एकमात्र तरीका git archaeology था, और मैंने Emacs का vc-annonate सीख लिया ताकि उसका आसानी से पीछा किया जा सके
  काम के code में भी कई बार ऐसा हुआ कि जिस codebase की मैं maintenance कर रहा था, उसका मूल लेखक बहुत पहले जा चुका था
  commit messages सिर्फ review के दौरान नहीं पढ़े जाते; वास्तव में बहुत-सी review UI तो commit messages छिपा देती हैं
  समस्या लंबा commit message अपने-आप में नहीं, बल्कि गलत तरीके से लिखा गया commit message ज़्यादा लगती है
  “commit messages, merge request descriptions, और code comments को स्पष्ट, मुद्दे पर और ज़रूरत-आधारित लिखो, और क्या नहीं बल्कि क्यों समझाओ” — यह दिशा-निर्देश अच्छा लगता है
  समस्या यह भी हो सकती है कि जो व्यक्ति पहले सिर्फ Fix Bugz 🚀️ लिखता था, वह अब “best practice” का पालन करने के नाम पर LLM से commit messages लिखवा रहा हो
  मेरा अनुमान है कि ज़्यादातर लोग commit messages इसलिए नहीं लिखते क्योंकि वे उन्हें पढ़ते नहीं हैं, और उन्हें पढ़ते नहीं क्योंकि GitHub web interface जैसी जगहों पर commits को देखते-देखते उन्हें ढूँढ़ने की activation energy ज़्यादा लगती है

  • “अनावश्यक विवरण ज़रूरत होने पर पूछे जा सकते हैं” वाली बात review के दौरान की है
    अगर जानकारी महत्वपूर्ण है, तो उसे comment के रूप में छोड़ा जा सकता है या commit message में जोड़ा जा सकता है
    KDE कुछ वर्षों से Gitlab का उपयोग कर रहा है

• लंबे समय में आने वाली पीढ़ियों के लिए सफल git archaeology के लिए संतुलन ज़रूरी है
  लोगों के बदल जाने या संदर्भ के दिमाग़ से मिट जाने की वजह से अक्सर बाद में उन दिखने में अनावश्यक लगने वाले विवरणों के बारे में पूछना संभव नहीं रहता
  उस संदर्भ को दर्ज करने का सबसे अच्छा समय वही है जब वह अभी आपके पास हो
  हो सकता है कि आप वास्तव में यह चाहते हों कि महत्वपूर्ण विवरण पहले रखे जाएँ और उन्हें किसी outline की तरह स्पष्ट रूप से अलग किया जाए

• PR या code explanation का मकसद क्या किया गया बताना नहीं, बल्कि क्यों किया गया बताना है
  उसे यह बताना चाहिए कि code ऐसा क्यों दिखता है और उसके पीछे क्या कारण है
  यह review के लिए भी अच्छा है, और बाद में git history में यह खोजने के लिए भी कि code ऐसा क्यों बना

• code explanation को सरल रखना महत्वपूर्ण है
  क्योंकि जिसे समझा या जिस पर ध्यान केंद्रित नहीं किया जा सकता, उसे पढ़ा भी नहीं जा सकता
  साथ ही software development करते समय बहुत सारा संदर्भ खो जाता है, और इस समय वह संदर्भ सिर्फ लेखक, उससे बात कर चुके लोगों, या code को गहराई से देख चुके लोगों के दिमाग़ में हो सकता है
  लेकिन मेरा मानना है कि उस संदर्भ को code के साथ ज़्यादा गहराई से जुड़ना चाहिए, कम नहीं
  आप हमेशा लेखक से बात नहीं कर सकते, इसलिए इसे ऐसी जगह लिखना चाहिए जो हमेशा सुलभ हो और code के साथ अपडेट होती रहे
  मौजूदा ज़्यादातर development workflows में उसके लिए सबसे उपयुक्त जगह git commit message है
  सबसे ऊपर summary लिखना अच्छा है, लेकिन मैं code change के बारे में अतिरिक्त व्याख्या भी छोड़ने की सलाह दूँगा
  अगर आप वह संदर्भ भी बाहर लिख दें जो अभी महत्वपूर्ण नहीं लगता, तो भविष्य का मैं आपका आभारी होगा
  आगे चलकर commit messages में ही ऐसा संदर्भ भर देने से बेहतर कोई तरीका चाहिए, और इसी वजह से मुझे व्यक्तिगत रूप से literate programming पसंद है, क्योंकि यह code के “क्या” और “क्यों” को समझाने के लिए ज़्यादा जगह देता है