Exercism की स्टाइल गाइड

यह दस्तावेज़ अभ्यासों में इस्तेमाल होने वाली भाषा और शब्दावली के लिए स्टाइल गाइड का काम करता है।

लागू करना

सभी अभ्यासों में इन नियमों का पालन होना चाहिए। मौजूदा विवरणों और टेस्ट केस को इन नियमों के अनुसार ढाला जा सकता है, इसके लिए "जगह लेने वाले" नए टेस्ट केस बनाने की ज़रूरत नहीं है।

एक ही अभ्यास के अंदर एकरूपता

कुछ शब्द ऐसे हैं जिनकी एक से अधिक सही वर्तनियाँ होती हैं (जैसे "lower case" और "lowercase")। जहाँ इस दस्तावेज़ में एक तय शैली नहीं बनी है, वहाँ एक अभ्यास के अंदर इनका इस्तेमाल एक जैसा ही होना चाहिए।

अपवाद

अगर सभी मेंटेनरों के बीच आम सहमति हो कि यह ठीक है, तो अभ्यास इन नियमों से अलग हो सकते हैं। उदाहरण के लिए, अलग-अलग इकाइयों के बीच बदलाव करने वाला कोई अभ्यास SI मापों का इस्तेमाल न करने का फैसला कर सकता है।

भाषा

सारी सामग्री US English में लिखी जानी चाहिए, जो UK English से कई तरह से अलग होती है। आगे चलकर दूसरे अनुवाद भी हो सकते हैं, लेकिन Exercism की "आधिकारिक" भाषा US English है।

माप

माप की सभी इकाइयाँ SI या SI से बनी इकाइयाँ होनी चाहिए।

संक्षेप, लघु रूप और आद्याक्षर

संक्षेप, लघु रूप और आद्याक्षर अक्सर दूसरे विकल्पों की तुलना में समझने में कठिन होते हैं, और सीखने की कोशिश कर रहे लोगों को ये अलग-थलग महसूस करा सकते हैं।

बहुत-से संक्षेप शब्दजाल होते हैं। जहाँ तक हो सके, दूसरे शब्द इस्तेमाल करके शब्दजाल से बचें। संक्षेप सिर्फ तभी इस्तेमाल कीजिए जब इनमें से कोई एक बात लागू हो:

  • संक्षिप्त रूप अपने पूरे रूप से अधिक प्रचलित हो।
  • संक्षेप के बिना पाठ बहुत लंबा और उलझा हुआ हो जाएगा।

संक्षेप इस्तेमाल करते समय हमेशा उसके पहले इस्तेमाल पर बताइए कि उसका मतलब क्या है। इसमें अक्सर संक्षेप का पूरा रूप लिखना शामिल होगा, लेकिन हमेशा नहीं। केवल संक्षेप का पूरा रूप लिख देना कम ही मौकों पर काफी होता है।

यहाँ कुछ उदाहरण नियम दिए गए हैं:

  • "IIRC" की जगह "if I recall correctly" लिखना बेहतर है।
  • "AFAIK" की जगह "as far as I know" लिखना बेहतर है।
  • "FIFO" की जगह "queue" और "FILO" की जगह "stack" लिखना बेहतर है।
  • किसी इंटरफेस को "RESTful" बताने की जगह उसकी खास विशेषताएँ बताइए।
  • अगर "CRUD" इस्तेमाल करना ही पड़े, तो समझाइए कि इसका पूरा रूप Create, Read, Update, Delete है और ये मानक डेटाबेस में होने वाली बुनियादी क्रियाएँ हैं।

और अच्छे इस्तेमाल के कुछ उदाहरण:

  • "HyperText Markup Language (HTML) is the language used to describe document structure and content on the web" (पूरा रूप दिया गया और समझाया गया)
  • "DNA, a set of chemical instructions that influence how our bodies are constructed" (DNA का पूरा रूप नहीं दिया गया, क्योंकि "deoxyribonucleic acid" से हमारे पाठकों को यह समझाने में मदद मिलने की उम्मीद कम है कि DNA क्या है)
  • "NASA, the United States' space agency, launched the Mariner 2 space probe in..." (NASA का पूरा रूप नहीं दिया गया, क्योंकि "National Aerospace and Space Administration" अपने पूरे नाम से कहीं ज़्यादा अपने संक्षेप से जाना जाता है)
  • "The Department of Motor Vehicles (DMV) is filled with sloths. That's why everything takes forever at the DMV" (DMV को पहली बार इस्तेमाल करते समय परिभाषित कीजिए)

व्याकरण

ऑक्सफोर्ड कॉमा

सूचियों में "ऑक्सफोर्ड कॉमा" (जिसे सीरियल कॉमा भी कहा जाता है) का इस्तेमाल कीजिए। उदाहरण के लिए, "I love my parents, Lady Gaga and Humpty Dumpty" लिखने की जगह "I love my parents, Lady Gaga, and Humpty Dumpty" लिखिए। समझाने वाली यह तस्वीर भी आपको पसंद आ सकती है।

अपवाद

कुछ संक्षेप इतने आम, उपयोगी और गैर-तकनीकी माने जाते हैं कि हमने उन्हें अनुमति दे दी है:

  • e.g. या eg
  • i.e. या ie
  • etc. या etc
  • docs

अभ्यास विवरणों में संकुचित रूप (जैसे "won't", "I'm", "that's") कम से कम इस्तेमाल कीजिए, या बिल्कुल नहीं; लेकिन साइट पर बाकी जगहों की भाषा (जैसे वेबसाइट की सामग्री, मेंटरिंग) में इन पर कोई रोक नहीं है।

American English की कई शैली-गाइड कहती हैं कि "i.e." और "e.g." जैसे संक्षेपों के बाद कॉमा लगना चाहिए (उदाहरण के लिए यह StackExchange थ्रेड देखिए)। Exercism के पाठ में यह मान्य है, लेकिन ज़रूरी नहीं।

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

गणितीय और शब्दजाल वाले शब्द

जहाँ भी गणितीय शब्द इस्तेमाल हों, वहाँ उन्हें समझाया जाना चाहिए, या उनकी जगह ऐसे शब्द लाने चाहिए जिनके लिए उस विषय का कम ज्ञान चाहिए।

उदाहरण:

  • "natural numbers" इस्तेमाल करने की जगह हमें "positive whole numbers" इस्तेमाल करना चाहिए।
  • अगर हम "rational numbers" कहना चाहते हैं, तो अभ्यास की भूमिका में इसे समझाना ज़रूरी है।
  • range शब्द (जिसका अलग-अलग संदर्भों में अलग मतलब हो सकता है) की जगह "x < ? < y (greater than x and less than y)" इस्तेमाल कीजिए।
  • "esoteric terms" की जगह "terms not understood by the majority of people" कहिए।

कोड

सारा कोड अपने ट्रैक की शैली के नियमों के अनुसार एक जैसी फॉर्मेटिंग में लिखा जाना चाहिए। जहाँ संभव हो, पूरे ट्रैक के ये नियम उस भाषा की पसंदीदा शैली के नियमों से मेल खाने चाहिए।