एनालाइज़र के कमेंट लिखना

यह दस्तावेज़ बताता है कि एनालाइज़र जो कमेंट बनाता है, उन्हें कैसे लिखें, और इसके लिए कुछ दिशा-निर्देश भी देता है।

सामग्री

एनालाइज़र कमेंट की सामग्री exercism/website-copy रेपो में एक Markdown डॉक्युमेंट के रूप में रखी जाती है। हर कमेंट में एक पॉइंटर स्ट्रिंग होती है, जिसका प्रारूप <track-slug>.<exercise-slug>.<comment-slug> होता है। यह स्ट्रिंग website-copy रेपो के किसी खास Markdown डॉक्युमेंट से जुड़ती है।

उदाहरण के लिए, ruby.two-fer.string-interpolation का मतलब यह डॉक्युमेंट है: https://github.com/exercism/website-copy/blob/main/analyzer-comments/ruby/two-fer/string_interpolation.md.

Note

अगर कोई कमेंट किसी भाषा से जुड़ा हो और किसी अभ्यास से नहीं, तो <exercise-slug> की जगह general लिखिए। जैसे ruby.general.string-explicit_return

शब्दों का चुनाव

  • बेवजह लंबे-चौड़े कमेंट लिखने से बचिए। संक्षिप्त रहिए।
  • तटस्थ भाव से निरीक्षण कीजिए; भावनात्मक कथनों और हर जगह लागू होने का दावा करने वाले कथनों से बचिए।
  • सुझाव स्पष्ट रखिए।
  • जहाँ संभव हो, पहले सुझाव दीजिए, फिर उसकी व्याख्या।
  • "me", "I", "we" जैसे शब्दों से बचिए, क्योंकि बॉट कोई व्यक्ति नहीं है।
  • "you" और "your code" से बचिए, क्योंकि इससे कभी-कभी कोड की नहीं, बल्कि व्यक्ति की परख होती दिखती है।
  • "just", "simply", "obviously" जैसे शब्दों से बचिए, क्योंकि ये नीचा दिखाने वाले लग सकते हैं: अगर कमेंट ज़रूरी है, तो वह बात obviously इतनी obvious नहीं थी।
  • लोग क्या जानते हैं और क्या नहीं, इस बारे में अनुमान मत लगाइए। एकमात्र अपवाद पहले पूरे किए जा चुके core अभ्यासों से मिला ज्ञान है। "as you know", "as you remember", "as you learned", "now that we all understand x" जैसे वाक्यांशों से बचिए, क्योंकि कुछ कह देने से यह ज़रूरी नहीं कि व्यक्ति उसे समझ भी गया हो।

दिशा-निर्देश

  • लक्ष्य प्रवाह है, निपुणता नहीं: Exercism पर किसी भाषा ट्रैक का उद्देश्य लोगों को यह मौका देना है कि वे थोड़ी निपुणता पर प्रवाह के ऊँचे स्तर तक पहुँच सकें। हमारा लक्ष्य भाषा के सिंटैक्स, मुहावरों और स्टैंडर्ड लाइब्रेरी में प्रवाह पाना है।
  • जहाँ संभव हो, मुहावरेदार कोड सुझाइए, यानी ऐसा कोड जो उस भाषा में कोड लिखने वाले लगभग सभी डेवलपर (शौकिया नहीं) लिखते हों। अगर कोई सुझाव मुहावरेदार नहीं है, तो यह बात बताइए और समझाइए कि वह सुझाव फिर भी क्यों काम का हो सकता है।
  • अंतर साफ़-साफ़ बताइए कि व्यक्ति क्या कर रहा है और उस भाषा में 'मुहावरेदार' क्या माना जाता है।
  • सही शब्दावली इस्तेमाल कीजिए, ताकि लोग उन अवधारणाओं को कहीं और पहचान सकें और खुद उन पर खोज भी कर सकें।
  • Exercism की पूरी मेंटरिंग के लिए आम सलाह के तौर पर हल मत बताइए। जब लोग खुद जवाब ढूँढ लेते हैं, तो सीखना टिकता है। यह बहुत रोमांचक अनुभव होता है, और उस भावना की चोट इसे यादगार बना देती है। लेकिन अगर खुद जवाब ढूँढने से खुशी का वह झटका न मिले, तो यह दिखाना बिलकुल बनता है कि हल कैसा दिखता है। उदाहरण के लिए, किसी मंज़ूर हल में छोटा-सा सुधार बताना कहीं कम रोमांचक होता है, जबकि किसी नामंज़ूर किए जा रहे हल पर सीखने वाली बात बताना ज़्यादा असरदार होता है, और इसलिए वहाँ लिंक के बजाय उदाहरण देना बनता है।
  • कमेंट को महत्व के क्रम में रखिए, पहला कमेंट सबसे महत्वपूर्ण और आखिरी कमेंट सबसे कम महत्वपूर्ण होना चाहिए।
  • कमेंट की संख्या सीमित रखिए। हर इटरेशन में एक से तीन कमेंट रखने का लक्ष्य रखिए।
  • एक ही विश्लेषण में एक ही कमेंट दो बार मत जोड़िए। एक ही कमेंट को अलग-अलग पैरामीटर के साथ जोड़ना दोहराव नहीं माना जाता।
  • अगर फॉर्मेटिंग या लिंटिंग भाषा का ज़रूरी हिस्सा हो, तो सिर्फ फॉर्मेटिंग पर कमेंट करने के बारे में सोचिए। जहाँ संभव हो, विद्यार्थियों को ऑटो-फॉर्मेटिंग के टूल की ओर भेजिए और/या भाषा की आधिकारिक स्टाइल गाइड का लिंक दीजिए।

शुरुआती कुछ अभ्यास

किसी ट्रैक के शुरुआती कुछ अभ्यासों के लिए नीचे दी गई बातें खास तौर पर ज़रूरी हैं:

  • कमेंट अपेक्षाकृत छोटा रखिए, टेक्स्ट की दीवार से या ढेर सारी सलाह से उन्हें बोझिल मत कीजिए। अगर पहले अभ्यास में उनका अनुभव अच्छा रहा, तो वे वापस आएँगे और आपको जो-जो बातें नज़र आईं, उन पर फीडबैक देने के कई और मौके मिलेंगे।
  • किसी अवधारणा को ज़रूरत से ज़्यादा मत समझाइए: कंपाइलर के भीतर चलने वाली प्रक्रियाओं वगैरह की गहराई में मत जाइए। यहाँ असल बात यह है कि यह भाषा ट्रैक के पहले अभ्यासों में से एक है, और इस पड़ाव पर फीडबैक छोटा और सीधा-निर्देशात्मक हो तो ज़्यादा मदद करता है।
  • ऐसा लिंक दीजिए जो ठीक-ठीक दिखाए कि उस अवधारणा को कैसे करना है, ट्यूटोरियल के अंदाज़ में। यानी यह दिखाना कि काम कैसे करें, यह चर्चा नहीं करना कि ऐसा क्यों है। इसका मतलब यह हो सकता है कि भाषा के आधिकारिक डॉक्युमेंट काफी न हों, क्योंकि वे अक्सर कोड का संदर्भ भर होते हैं और यह नहीं दिखाते कि उसे इस्तेमाल कैसे करें और वह कैसे काम करता है। लेकिन लिंक सिर्फ और गहराई में जाने के लिए ही दीजिए। व्यक्ति को लिंक खोले बिना, सीधे आपके जवाब से ही समझ आ जाना चाहिए कि आपका मतलब क्या है।

उदाहरण

JavaScript में एक विद्यार्थी ने let से एक टॉप-लेवल कॉन्स्टेंट लिखा है।

<!-- not following these guidelines -->

As you know, everyone uses const, you shouldn't use let or var.

यह कमेंट इन दिशा-निर्देशों का पालन नहीं करता, और इसकी वजहें ये हैं:

  • सुझाया गया काम "व्याख्या" के बाद आता है।
  • "As you know": हमें नहीं पता कि विद्यार्थी को यह बात पता है या नहीं।
  • "you shouldn't": यह बात कहने के लिए "you" की ज़रूरत नहीं है।
  • "everyone uses const": यह सच नहीं है और इससे विद्यार्थी को लग सकता है कि उसने कोई बहुत बड़ी गलती कर दी है।
  • इसमें यह असली व्याख्या नहीं है कि यह सलाह क्यों दी जा रही है।
<!-- better -->

Prefer `const` and `let` over `var`. The `const` declaration stops a variable
from being accidentally reassigned, which provides safety, and reduces
cognitive load for someone reading the code. [This article](https://medium.com/javascript-scene/javascript-es6-var-let-or-const-ba58b8dcde75)
explains the difference between the three.

Go में एक विद्यार्थी ने बिल्ट-इन एरर की जगह अपना कस्टम एरर बनाया है:

<!-- not following these guidelines -->

I see you are creating a custom `error`. This is perfectly fine! If you did not
know about `errors.New` and `fmt.Errorf` have a look at them as they are much
simpler ways to create an error. Custom errors are helpful if you want to check
if an error is of a certain type later.

यह कमेंट इन दिशा-निर्देशों का पालन नहीं करता, और इसकी वजहें ये हैं:

  • "I see": एनालाइज़र कोई व्यक्ति नहीं है: "I" से बचिए।
  • "This is perfectly fine!": ज़ाहिर है कि बात ठीक नहीं है, वरना भरोसा दिलाने की ज़रूरत ही न होती। इसे पूरी तरह छोड़ा जा सकता है; अगर आप किसी चीज़ के मौजूद होने के बारे में सामान्य टिप देना चाहते हैं, तो ठीक यही कहिए: "x करने का एक और बराबर सही तरीका y है।"
  • "If you did not know about": शब्दों का यह बेवजह लंबा समूह छोड़ दीजिए।
<!-- better -->

A custom `error` is typically used to provide custom behavior, or to distinguish
on type later. For simpler cases, it's more common to rely on `errors.New` or
`fmt.Errorf`. This [in-depth article](https://golangbot.com/custom-errors/) about
custom errors might be interesting.

CI

चूँकि कमेंट एनालाइज़र के साथ एक ही रेपो में नहीं रहते, हर एनालाइज़र में ऐसा CI होना चाहिए जो यह जाँचे कि उस खास एनालाइज़र में इस्तेमाल होने वाले कमेंट (यानी वे जो आउटपुट बन सकते हैं) exercism/website-copy रेपो की main ब्रांच पर मौजूद कमेंट हैं।

यह लिखते समय, इस CI के किसी सामान्यीकरण की स्थिति (अगर हो) इस issue में देखी जा सकती है।