कॉन्सेप्ट अभ्यास

कॉन्सेप्ट अभ्यास ऐसे अभ्यास हैं जो खास (प्रोग्रामिंग) कॉन्सेप्ट सिखाने के लिए बनाए गए हैं। कॉन्सेप्ट अभ्यास जो कॉन्सेप्ट सिखाते हैं, वे मिलकर एक सिलेबस बनाते हैं। सिलेबस डिज़ाइन करने के तरीके के बारे में अधिक जानने के लिए सिलेबस डॉक्यूमेंटेशन देखिए।

Note

ट्रैक की मूल डायरेक्टरी से ये कमांड चलाकर आप जल्दी से एक नया कॉन्सेप्ट अभ्यास तैयार कर सकते हैं:

bin/fetch-configlet
bin/configlet create --concept-exercise <slug>

अधिक जानकारी के लिए configlet create डॉक्स देखिए।

मेटाडेटा

कॉन्सेप्ट अभ्यास का मेटाडेटा config.json फाइल की exercises.concept key में तय किया जाता है। यह मेटाडेटा अभ्यास का UUID, स्लग और बहुत कुछ तय करता है।

उदाहरण

{
  "exercises": {
    "concept": [
      {
        "uuid": "93fbc7cf-3a7e-4450-ad22-e30129c36bb9",
        "slug": "cars-assemble",
        "name": "Cars, Assemble!",
        "concepts": ["if-statements", "numbers"],
        "prerequisites": ["basics"]
      }
    ]
  }
}

फाइलें

हर कॉन्सेप्ट अभ्यास की अपनी डायरेक्टरी ट्रैक की exercises/concept डायरेक्टरी के अंदर होती है। कॉन्सेप्ट अभ्यास की डायरेक्टरी का नाम उस अभ्यास की slug प्रॉपर्टी से मेल खाना चाहिए, जो config.json फाइल में तय की गई है।

कॉन्सेप्ट अभ्यास में चार तरह की फाइलें होती हैं:

डॉक्यूमेंटेशन फाइलें

ये फाइलें छात्र के सामने रखी जाती हैं, ताकि अभ्यास को समझाने में मदद मिले।

  • .docs/introduction.md: छात्र को वे कॉन्सेप्ट बताती है जो यह अभ्यास सिखाता है (आवश्यक)।
  • .docs/instructions.md: अभ्यास के निर्देश देती है (आवश्यक)।
  • .docs/hints.md: अभ्यास में अटके छात्र की मदद के लिए संकेत देती है (आवश्यक)।

मेटाडेटा फाइलें

ये फाइलें छात्र के सामने नहीं रखी जातीं, बल्कि अभ्यास का मेटाडेटा तय करने के लिए इस्तेमाल होती हैं।

  • .meta/config.json: अभ्यास की मेटा जानकारी रखती है (आवश्यक)।
  • .meta/design.md: अभ्यास का डिज़ाइन बताती है (आवश्यक)।

अप्रोच फाइलें

ये फाइलें अभ्यास के अप्रोच बताती हैं।

  • .approaches/introduction.md: अभ्यास के सबसे आम अप्रोच का परिचय (वैकल्पिक)।
  • .approaches/config.json: अप्रोच का मेटाडेटा (वैकल्पिक)।
  • .approaches/<approach-slug>/content.md: अप्रोच का विवरण (वैकल्पिक)।
  • .approaches/<approach-slug>/snippet.txt: अप्रोच दिखाने वाला स्निपेट (वैकल्पिक)।

आर्टिकल फाइलें

ये फाइलें अभ्यास के आर्टिकल बताती हैं।

  • .articles/config.json: आर्टिकल का मेटाडेटा (वैकल्पिक)।
  • .articles/<article-slug>/content.md: आर्टिकल का विवरण (वैकल्पिक)।
  • .articles/<article-slug>/snippet.md: आर्टिकल दिखाने वाला स्निपेट (वैकल्पिक)।

अभ्यास फाइलें

भाषा के हिसाब से अलग होने वाली फाइलें, जैसे इम्प्लीमेंटेशन और टेस्ट फाइलें। इन फाइलों के नाम हर ट्रैक में अलग होते हैं।

  • टेस्ट सूट: जाँचता है कि हल सही है या नहीं (आवश्यक)।
  • स्टब इम्प्लीमेंटेशन: छात्रों को शुरुआत करने की जगह देता है (आवश्यक)।
  • एक्ज़ेम्प्लर इम्प्लीमेंटेशन: एक ऐसा इम्प्लीमेंटेशन देता है जो भाषा के स्वाभाविक तरीके के मुताबिक़ है और सारे टेस्ट पास करता है (आवश्यक)।
  • अतिरिक्त फाइलें: ताकि टेस्ट चल सकें (वैकल्पिक)।

उदाहरण

exercises
└── concept
    └── cars-assemble
        ├── .approaches
        |   ├── for-loop
        |   |   ├── content.md
        |   |   └── snippet.txt
        |   ├── config.json
        |   └── introduction.md
        ├── .articles
        |   ├── performance
        |   |   ├── content.md
        |   |   └── snippet.md
        |   └── config.json
        ├── .docs
        |   ├── introduction.md
        |   ├── instructions.md
        |   └── hints.md
        ├── .meta
        |   ├── config.json        
        |   ├── design.md
        |   └── Exemplar.cs (exemplar implementation)
        ├── CarsAssemble.cs (stub implementation)
        └── CarsAssemblyTests.cs (tests)

न्यूनतम मान्य स्पेक

नए अभ्यासों के लिए हम "ऑप्टिमिस्टिक मर्जिंग" का तरीका अपनाते हैं, जिसमें ट्रैक किसी अभ्यास को "कार्य प्रगति पर" स्थिति में विकसित कर सकते हैं। वह न्यूनतम मान्य स्थिति, जिसमें configlet पास हो जाएगा और आप मर्ज कर सकेंगे, यह है:

  • ट्रैक की config.json में एक मान्य एंट्री, जिसमें status को wip पर सेट किया गया हो।
  • एक मान्य .meta/config.json फाइल।
  • ये फाइलें मौजूद हों, भले ही खाली हों:
    • .docs/introduction.md
    • .docs/instructions.md
    • .docs/hints.md
    • स्टब इम्प्लीमेंटेशन
    • टेस्ट फाइल

फाइल: .docs/introduction.md

उद्देश्य: छात्र को वे कॉन्सेप्ट बताना जो यह अभ्यास सिखाता है।

उपस्थिति: आवश्यक

  • दी गई जानकारी छात्र को इतना संदर्भ दे, जितने से वह खुद हल निकाल सके।
  • सिर्फ वही जानकारी दीजिए जो कॉन्सेप्ट की बुनियादी बातें समझने और अभ्यास हल करने के लिए ज़रूरी है। बाकी जानकारी कॉन्सेप्ट के about.md डॉक्यूमेंट के लिए छोड़ दीजिए।
  • लिंक कम से कम इस्तेमाल कीजिए, बेहतर हो कि बिल्कुल न हों। रिकर्शन जैसे जटिल विषय को समझाने वाला लिंक भले काम का हो, लेकिन ज़्यादातर कॉन्सेप्ट में लिंक ज़रूरत से ज़्यादा जानकारी दे देते हैं, इसलिए कोशिश यह होनी चाहिए कि बात संक्षेप में वहीं समझा दी जाए।
  • सही तकनीकी शब्द इस्तेमाल कीजिए, ताकि छात्र आसानी से और जानकारी खोज सके।
  • कोड के उदाहरण सिर्फ नया सिंटैक्स बताने के लिए इस्तेमाल कीजिए (छात्रों को सिंटैक्स के उदाहरण वेब पर खोजने की ज़रूरत न पड़े)। बाकी जगह कोड की जगह विवरण या लिंक दीजिए।

उदाहरण के लिए, "स्ट्रिंग" वाले अभ्यास का परिचय स्ट्रिंग को बस "यूनिकोड अक्षरों का क्रम" या "बाइट्स की श्रृंखला" कहकर बता सकता है, उपयोगकर्ताओं को बता सकता है कि स्ट्रिंग कैसे बनाई जाती है, और समझा सकता है कि स्ट्रिंग में मेथड होते हैं जिनसे उसे बदला जा सकता है। जब तक अभ्यास हल करने के लिए छात्र को इससे बारीक बातें समझने की ज़रूरत न हो, इस तरह की छोटी व्याख्या (और उसकी सिंटैक्स का एक उदाहरण) छात्र के लिए अभ्यास हल करने भर की जानकारी होनी चाहिए।

उदाहरण

# Introduction

There are two primary ways to assign objects to names in Ruby - using variables or constants. Variables are always written in snake case. A variable can reference different objects over its lifetime. For example, `my_first_variable` can be defined and redefined many times using the `=` operator:

```ruby
my_first_variable = 1
my_first_variable = "Some string"
my_first_variable = SomeComplexObject.new
```

फाइल: .docs/introduction.md.tpl

उद्देश्य: वह टेम्पलेट जिससे introduction.md फाइल बनाई जाती है।

उपस्थिति: वैकल्पिक

introduction.md डॉक्यूमेंट छात्र को अभ्यास के कॉन्सेप्ट बताता है। हर कॉन्सेप्ट का अपना अलग introduction.md डॉक्यूमेंट भी होता है, जो अभ्यास के संदर्भ के बाहर नहीं दिखाया जाता।

अगर कॉन्सेप्ट का परिचय अभ्यास के परिचय में ज्यों का त्यों शामिल करना हो, तो introduction.md.tpl फाइल इस्तेमाल की जा सकती है। यह फाइल प्लेसहोल्डर के ज़रिए कॉन्सेप्ट के परिचय का हवाला देने देती है: %{concept:<concept-slug>}।

configlet टेम्पलेट फाइल से introduction.md फाइल बना सकता है। बनी हुई फाइल में कॉन्सेप्ट वाले प्लेसहोल्डर की जगह उस कॉन्सेप्ट की introduction सामग्री आ जाती है।

Exercism वेबसाइट को सिर्फ introduction.md डॉक्यूमेंट की जानकारी होती है। टेम्पलेट फाइल इस्तेमाल होने पर introduction.md बनाना ट्रैक की ज़िम्मेदारी है।

ट्रैक हर अभ्यास के लिए तय कर सकते हैं कि टेम्पलेट इस्तेमाल करना है या नहीं। कुछ मामलों में कॉन्सेप्ट का परिचय ज्यों का त्यों इस्तेमाल करना सबसे अच्छा नहीं होता। हमेशा वही चुनिए जिससे छात्र को सीखने का सबसे अच्छा अनुभव मिले।

उदाहरण

# Introduction

%{concept:variables}

फाइल: .docs/instructions.md

उद्देश्य: अभ्यास के निर्देश देना।

उपस्थिति: आवश्यक

यह फाइल दो हिस्सों में बँटी होती है।

  1. पहला हिस्सा अभ्यास की "कहानी" या "विषय" समझाता है। इसमें आम तौर पर कोड के उदाहरण नहीं होने चाहिए।
  2. दूसरा हिस्सा साफ़ निर्देश देता है कि छात्र को क्या करना है, एक या ज़्यादा टास्क के रूप में।

हर टास्क को इन नियमों का पालन करना चाहिए:

  • दूसरे स्तर की हेडिंग से शुरू हो, जो किसी संख्या से शुरू हो (जैसे ## 1. Do X, ## 2. Do Y)।
  • हेडिंग बताए कि क्या लागू करना है, यह नहीं कि कैसे (जैसे ## 1. Check if an appointment has already passed)।
  • बताइए कि छात्र को कौन-सा फंक्शन/मेथड बनाना या लागू करना है (जैसे Implement method X(...) that takes an A and returns a Z),
  • उस फंक्शन के इस्तेमाल का एक उदाहरण कोड में दीजिए। ये उदाहरण टेस्ट में दिए गए उदाहरणों से अलग होने चाहिए।

हमारे लिए यह बहुत ज़रूरी है कि Exercism की सामग्री सबके लिए सुरक्षित रहे, इसलिए कहानियाँ उपयुक्त हैं या नहीं, यह तय करते समय हम अक्सर सतर्कता की तरफ झुकते हैं। हम मर्ज करते समय सावधानी बरतते हैं, लेकिन हम मानते हैं कि यह पहचानना मुश्किल है कि किसी को क्या आपत्तिजनक लग सकता है। इसलिए हम हमेशा यह मानकर चलेंगे कि आप अच्छे इरादे से काम कर रहे हैं, और रिव्यू में किसी भी दिक्कत को बिना टकराव के पकड़ने की पूरी कोशिश करेंगे। अगर आप कोई कहानी हमसे जाँचवाना चाहें, तो @exercism/leadership का ज़िक्र कीजिए और हम उसे साथ में देखेंगे। यहाँ कुछ दिशानिर्देश दिए गए हैं:

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

उदाहरण

# Instructions

In this exercise you're going to write some code to help you cook a brilliant lasagna from your favorite cooking book.

## 1. Calculate the remaining oven time in minutes

Define the `Lasagna#remaining_minutes_in_oven` method that takes the actual minutes the lasagna has been in the oven as a parameter and returns how many minutes the lasagna still has to remain in the oven, based on the expected oven time in minutes from the previous task.

```ruby
lasagna = Lasagna.new
lasagna.remaining_minutes_in_oven(30)
# => 10
```

फाइल: .docs/hints.md

उद्देश्य: छात्र को संकेत देना, ताकि अभ्यास में अटकने पर वह आगे बढ़ सके।

उपस्थिति: आवश्यक

  • अगर छात्र अटक जाए, तो हम उसे संकेत माँगने वाला बटन क्लिक करने देंगे, जिससे फाइल का संबंधित हिस्सा दिखेगा।
  • संकेत हेडिंग के नीचे बुलेट पॉइंट में होने चाहिए।
  • संकेत लगभग हर छात्र को आगे बढ़ाने के लिए काफी होने चाहिए।
  • संकेतों में हल सीधे न लिखा हो, बल्कि ऐसा संसाधन बताया जाए जो हल समझाए (जैसे इस्तेमाल करने वाले फंक्शन के डॉक्यूमेंटेशन का लिंक देना)।
  • संकेत कॉन्सेप्ट समझाने के लिए कोड के उदाहरण दिखा सकते हैं, पर हल का खाका नहीं। जैसे किसी ऐरे वाले अभ्यास में वे दिखा सकते हैं कि कोई ऐरे फंक्शन कैसे काम करता है, लेकिन ऐसे नहीं कि उसे सीधे कॉपी करके हल में चिपकाया जा सके।
  • अभ्यास के बारे में सामान्य संकेत ## General हेडिंग के नीचे Markdown लिस्ट के रूप में हो सकते हैं।
  • टास्क से जुड़े संकेत उन हेडिंग के नीचे Markdown लिस्ट में हों जो instructions.md में उसी टास्क की हेडिंग से मेल खाती हों (जैसे ## 2. Do Y)।
  • अगर सामान्य संकेत न हों या किसी खास टास्क के लिए संकेत न हों, तो वे हेडिंग छोड़ दीजिए। हर हेडिंग के बाद एक Markdown लिस्ट होनी चाहिए।
  • सामान्य संकेतों से ज़्यादा टास्क से जुड़े संकेतों को प्राथमिकता दीजिए, क्योंकि टास्क से जुड़े संकेत छात्र को आगे बढ़ाने में ज़्यादा काम आते हैं।
  • टास्क की हेडिंग बताए कि टास्क में क्या करना है, यह नहीं कि कैसे।
  • टास्क की हेडिंग सामान्य वाक्य की तरह लिखी जाए (सिर्फ पहला अक्षर बड़ा) (जैसे ## 2. Check if a book can be borrowed)।
  • टास्क में साफ़ हो कि कौन-सा मेथड/फंक्शन/टाइप लागू करना है और उसकी अपेक्षित वैल्यू क्या है (जैसे Implement the 'canBorrowBook' function to check if a book can be borrowed. The function takes a book as its parameter and returns `true` if the book has not already been borrowed; otherwise, return `false`)।

संकेत देखना कोई "सिफारिश किया गया" रास्ता नहीं होगा और जब तक छात्र उसके बिना आगे न बढ़ सके, हम (हल्के-फुल्के तरीके से) उसे इस्तेमाल करने से हतोत्साहित करेंगे। इसलिए यह ध्यान रखने लायक है कि संकेत पढ़ते समय छात्र थोड़ा उलझा हुआ या बोझ महसूस कर सकता है, और शायद निराश भी हो सकता है।

उदाहरण

# Hints

## General

- You need to define a [constant][constant] which should contain the [integer][integers] value specified in the recipe.

## 1. Calculate the remaining oven time in minutes

- You need to define a [method][methods] with a single parameter for the actual time so far.

[constants]: https://www.rubyguides.com/2017/07/ruby-constants/
[integers]: https://ruby-doc.org/core-2.7.0/Integer.html
[methods]: https://launchschool.com/books/ruby/read/methods

फाइल: .meta/design.md

उद्देश्य: अभ्यास का डिज़ाइन बताना।

उपस्थिति: आवश्यक

इस फाइल में अभ्यास के डिज़ाइन की जानकारी होती है, जिसमें उसका लक्ष्य, सिखाने के लक्ष्य, क्या नहीं सिखाना है, और बहुत कुछ शामिल है। यह जानकारी अभ्यास से जुड़े GitHub issue से निकाली जा सकती है।

यह इसलिए होती है ताकि आगे के मेंटेनरों या योगदानकर्ताओं को अभ्यास के दायरे और सीमाओं की जानकारी मिले, और समय के साथ अभ्यासों को और जटिल बनाने की स्वाभाविक प्रवृत्ति से बचा जा सके।

उदाहरण

# Design

## Goal

The goal of this exercise is to teach the student the basics of programming in Ruby.

## Learning objectives

- Know what a variable is.
- Know how to define a variable.
- Know how to update a variable.

## Out of scope

- Memory and performance characteristics.
- Method overloads.

## Concepts

The Concepts this exercise unlocks are:

- `basics`: know what a variable is; know how to define a variable; know how to update a variable.

## Prerequisites

There are no prerequisites.

फाइल: .meta/config.json

उद्देश्य: अभ्यास की मेटा जानकारी रखना।

उपस्थिति: आवश्यक

इस फाइल में अभ्यास की मेटा जानकारी होती है:

  • authors: अभ्यास के लेखक/लेखकों के GitHub यूज़रनेम (आवश्यक)
    • अगर रिव्यूअर के रिव्यू से अभ्यास में बड़ा बदलाव हुआ हो तो उन्हें भी शामिल कीजिए (इतना कि लगे "यह आपने मिलकर किया है")।
  • contributors: अभ्यास के योगदानकर्ता/योगदानकर्ताओं के GitHub यूज़रनेम (वैकल्पिक)
    • अगर रिव्यूअर के रिव्यू काम के या अमल में लाने लायक हों, तो उन्हें भी शामिल कीजिए।
  • forked_from: यह किस अभ्यास से फोर्क किया गया है (अगर अभ्यास फोर्क किया गया हो तो आवश्यक)।
  • files: इस अभ्यास में इस्तेमाल होने वाली फाइलों की जगह, अभ्यास की डायरेक्टरी के सापेक्ष (आवश्यक)
  • language_versions: भाषा के वर्ज़न की ज़रूरतें (वैकल्पिक)
  • blurb: इस अभ्यास का छोटा विवरण। इसकी लंबाई <= 350 होनी चाहिए। Markdown का समर्थन नहीं है (आवश्यक)
  • source: वह स्रोत जिस पर यह अभ्यास आधारित है (वैकल्पिक)
  • source_url: उस स्रोत का URL जिस पर यह अभ्यास आधारित है (वैकल्पिक)
  • representer: इस बारे में मेटा जानकारी कि रेप्रेज़ेंटर इस फाइल को कैसे प्रोसेस करता है (वैकल्पिक)
    • version: अभ्यास के लिए इस्तेमाल होने वाले रेप्रेज़ेंटर के वर्ज़न का पूर्णांक (अगर मुख्य key मौजूद हो तो आवश्यक)
  • icon: आइकन का स्लग (देखिए आइकनों की पूरी सूची)। अगर तय न किया गया हो, तो अभ्यास का स्लग इस्तेमाल होगा (वैकल्पिक)
  • custom: अभ्यास से जुड़ा कोई भी गैर-मानक डेटा। इससे हर अभ्यास के लिए ट्रैक की टूलिंग का व्यवहार बदला जा सकता है (वैकल्पिक)

अगर कोई व्यक्ति लेखक भी हो और योगदानकर्ता भी, तो उसे सिर्फ लेखक के रूप में लिखिए।

न्यूनतम उदाहरण

{
  "authors": ["FSharpForever"],
  "files": {
    "solution": ["Lasagna.fs"],
    "test": ["LasagnaTests.fs"],
    "exemplar": [".meta/Exemplar.fs"]
  },
  "blurb": "Learn the basics of F# by cooking Lucian's Luscious Lasagna"
}

पूरा उदाहरण

मान लीजिए कि उपयोगकर्ता FSharpForever ने F# ट्रैक के लिए log-levels नाम का अभ्यास लिखा है। PythonProfessor उस अभ्यास को Python ट्रैक के लिए ढालता है। बाद में उपयोगकर्ता GladToHelp उस अभ्यास को बेहतर बनाता है।

{
  "authors": ["PythonProfessor"],
  "contributors": ["GladToHelp"],
  "files": {
    "solution": ["log_levels.py"],
    "test": ["log_levels_test.py"],
    "exemplar": [".meta/exemplar.py"],
    "editor": ["test_helper.py"]
  },
  "forked_from": ["fsharp/log-levels"],
  "language_versions": ">=3.7",
  "blurb": "Learn how to work with strings by processing log lines.",
  "source": "Wikipedia",
  "source_url": "https://en.wikipedia.org/wiki/Log_file",
  "representer": {
    "version": 2
  },
  "icon": "logs",
  "custom": {
    "parallel": true
  }
}

ध्यान दीजिए:

  • लेखकों और योगदानकर्ताओं का क्रम मायने नहीं रखता और उसका कोई अर्थ नहीं है।
  • अगर आप किसी अभ्यास को फोर्क कर रहे हैं, तो मूल लेखकों या योगदानकर्ताओं का ज़िक्र न कीजिए। बस यह पक्का कीजिए कि forked_from सही है।
  • भले ही यह आम न हो, पर कई अभ्यासों से फोर्क करना संभव है।
  • language_versions एक खुली स्ट्रिंग है, जिसे ट्रैक अपनी मर्ज़ी से इस्तेमाल और समझ सकते हैं।

फाइल: .approaches/introduction.md

उद्देश्य: अभ्यास के सबसे आम अप्रोच का परिचय

उपस्थिति: वैकल्पिक

यह फाइल अभ्यास के सबसे आम अप्रोच बताती है। इस फाइल में क्या होना चाहिए, इसकी अधिक जानकारी के लिए डॉक्यूमेंटेशन देखिए।

उदाहरण

# Introduction

The key to this exercise is to deal with C# strings being immutable, which means that a `string`'s value cannot be changed.
Therefore, to reverse a string you'll need to create a _new_ `string`.

## Using LINQ

```csharp
public static string Reverse(string input)
{
    return new string(input.Reverse().ToArray());
}
```

For more information, check the [LINQ approach][approach-linq].

## Which approach to use?

If readability is your primary concern (and it usually should be), the LINQ-based approach is hard to beat.

फाइल: .approaches/config.json

उद्देश्य: अप्रोच का मेटाडेटा

उपस्थिति: वैकल्पिक (जब कोई अप्रोच परिचय या अप्रोच मौजूद हो तो आवश्यक)

इस फाइल में अभ्यास के अप्रोच की मेटा जानकारी होती है:

  • introduction: अभ्यास के अप्रोच परिचय के लेखकों के GitHub यूज़रनेम (वैकल्पिक)

    • authors: अभ्यास के अप्रोच परिचय के लेखकों के GitHub यूज़रनेम (आवश्यक)
      • अगर रिव्यूअर के रिव्यू से अभ्यास का अप्रोच परिचय बड़े पैमाने पर बदला हो तो उन्हें भी शामिल कीजिए (इतना कि लगे "यह आपने मिलकर किया है")।
    • contributors: अभ्यास के अप्रोच परिचय के योगदानकर्ताओं के GitHub यूज़रनेम (वैकल्पिक)
      • अगर रिव्यूअर के रिव्यू काम के या अमल में लाने लायक हों, तो उन्हें भी शामिल कीजिए।

  • approaches: विस्तृत अप्रोच की सूची देने वाला ऐरे (वैकल्पिक)

    • uuid: एक V4 UUID जो अप्रोच की पहचान अलग-अलग तरीके से करता है। यह UUID ट्रैक के अंदर भी और सारे ट्रैकों में भी अलग होना चाहिए, और कभी नहीं बदलना चाहिए
    • slug: अप्रोच का स्लग, जो छोटे अक्षरों में और kebab-case में होता है। यह स्लग ट्रैक के अंदर सारे अप्रोच स्लगों में अलग होना चाहिए। इसकी लंबाई <= 255 होनी चाहिए।
    • title: अप्रोच का शीर्षक। इसकी लंबाई <= 255 होनी चाहिए।
    • blurb: इस अप्रोच का छोटा विवरण। इसकी लंबाई <= 350 होनी चाहिए। Markdown का समर्थन नहीं है (आवश्यक)
    • authors: अभ्यास के अप्रोच के लेखकों के GitHub यूज़रनेम (आवश्यक)
      • अगर रिव्यूअर के रिव्यू से अभ्यास का अप्रोच बड़े पैमाने पर बदला हो तो उन्हें भी शामिल कीजिए (इतना कि लगे "यह आपने मिलकर किया है")।
    • contributors: अभ्यास के अप्रोच के योगदानकर्ताओं के GitHub यूज़रनेम (वैकल्पिक)
      • अगर रिव्यूअर के रिव्यू काम के या अमल में लाने लायक हों, तो उन्हें भी शामिल कीजिए।
    • tags: वे शर्तें बताइए जिनके होने पर कोई सबमिशन किसी अप्रोच से जुड़ जाता है। (वैकल्पिक)
      • all: ऐसे टैग का ऐरे जो सब-के-सब सबमिशन पर मौजूद होने चाहिए (वैकल्पिक, जब तक कि any में कोई एलिमेंट न हो)
      • any: ऐसे टैग का ऐरे जिनमें से कम से कम एक सबमिशन पर मौजूद होना चाहिए (वैकल्पिक, जब तक कि all में कोई एलिमेंट न हो)
      • not: इनमें से कोई भी टैग सबमिशन पर मौजूद न हो (वैकल्पिक)

उदाहरण

{
  "introduction": {
    "authors": ["erikschierboom"]
  },
  "approaches": [
    {
      "uuid": "448fb2b4-18ab-4e55-aa54-ad4ed6d5f7f6",
      "slug": "span",
      "title": "Use Span<T>",
      "blurb": "Use Span<T> to efficiently reverse a string.",
      "authors": ["erikschierboom"]
    }
  ]
}

फाइल: .approaches/<approach-slug>/content.md

उद्देश्य: अप्रोच का विस्तृत विवरण

उपस्थिति: वैकल्पिक (अप्रोच के लिए आवश्यक)

इस फाइल में अप्रोच का विस्तृत विवरण होता है। इस फाइल में क्या होना चाहिए, इसकी अधिक जानकारी के लिए डॉक्यूमेंटेशन देखिए।

उदाहरण

# Span

```csharp
Span<char> chars = stackalloc char[input.Length];
for (var i = 0; i < input.Length; i++)
{
    chars[input.Length - 1 - i] = input[i];
}
return new string(chars);
```

This `Span<T>` approach uses a `for` loop.

फाइल: .approaches/<approach-slug>/snippet.txt

उद्देश्य: अप्रोच दिखाने वाला स्निपेट

उपस्थिति: वैकल्पिक (अप्रोच के लिए आवश्यक)

इस फाइल में एक छोटा स्निपेट होता है जो अप्रोच दिखाता है। यह स्निपेट अभ्यास के Dig Deeper पेज पर दिखाया जाता है।

इसकी लाइनों की संख्या <= 8 होनी चाहिए।

इस फाइल में क्या होना चाहिए, इसकी अधिक जानकारी के लिए डॉक्यूमेंटेशन देखिए।

उदाहरण

Span<char> chars = stackalloc char[input.Length];
for (var i = 0; i < input.Length; i++)
{
    chars[input.Length - 1 - i] = input[i];
}
return new string(chars);

फाइल: .article/config.json

उद्देश्य: आर्टिकल का मेटाडेटा

उपस्थिति: वैकल्पिक (जब कोई आर्टिकल मौजूद हो तो आवश्यक)

इस फाइल में अभ्यास के आर्टिकल की मेटा जानकारी होती है:

  • articles: विस्तृत आर्टिकल की सूची देने वाला ऐरे (वैकल्पिक)
    • uuid: एक V4 UUID जो आर्टिकल की पहचान अलग-अलग तरीके से करता है। यह UUID ट्रैक के अंदर भी और सारे ट्रैकों में भी अलग होना चाहिए, और कभी नहीं बदलना चाहिए
    • slug: आर्टिकल का स्लग, जो छोटे अक्षरों में और kebab-case में होता है। यह स्लग ट्रैक के अंदर सारे आर्टिकल स्लगों में अलग होना चाहिए। इसकी लंबाई <= 255 होनी चाहिए।
    • title: आर्टिकल का शीर्षक। इसकी लंबाई <= 255 होनी चाहिए।
    • blurb: इस आर्टिकल का छोटा विवरण। इसकी लंबाई <= 350 होनी चाहिए। Markdown का समर्थन नहीं है (आवश्यक)
    • authors: अभ्यास के आर्टिकल के लेखकों के GitHub यूज़रनेम (आवश्यक)
      • अगर रिव्यूअर के रिव्यू से अभ्यास का आर्टिकल बड़े पैमाने पर बदला हो तो उन्हें भी शामिल कीजिए (इतना कि लगे "यह आपने मिलकर किया है")।
    • contributors: अभ्यास के आर्टिकल के योगदानकर्ताओं के GitHub यूज़रनेम (वैकल्पिक)
      • अगर रिव्यूअर के रिव्यू काम के या अमल में लाने लायक हों, तो उन्हें भी शामिल कीजिए।

उदाहरण

{
  "articles": [
    {
      "uuid": "6db71962-62d5-448b-a980-c20ae41013ed",
      "slug": "performance",
      "title": "Optimizing performance",
      "blurb": "Explore how to most efficiently reverse a string and what the trade-offs are.",
      "authors": ["erikschierboom"]
    }
  ]
}

फाइल: .articles/<article-slug>/content.md

उद्देश्य: अप्रोच का विस्तृत विवरण

उपस्थिति: वैकल्पिक (अप्रोच के लिए आवश्यक)

इस फाइल में अप्रोच का विस्तृत विवरण होता है। इस फाइल में क्या होना चाहिए, इसकी अधिक जानकारी के लिए डॉक्यूमेंटेशन देखिए।

उदाहरण

# Performance

In this document, we'll find out which approach is the most performant one.

## Benchmark results

| Method |      Mean |     Error |    StdDev |    Median | Allocated |
| -----: | --------: | --------: | --------: | --------: | --------: |
|   Linq | 29.133 ns | 0.5865 ns | 0.5486 ns | 28.984 ns |      80 B |
|  Array |  4.806 ns | 0.4999 ns | 1.4739 ns |  3.967 ns |         - |

फाइल: .articles/<article-slug>/snippet.txt

उद्देश्य: अप्रोच दिखाने वाला स्निपेट

उपस्थिति: वैकल्पिक (आर्टिकल के लिए आवश्यक)

इस फाइल में एक छोटा स्निपेट होता है जो आर्टिकल दिखाता है। यह स्निपेट अभ्यास के Dig Deeper पेज पर दिखाया जाता है।

इसकी लाइनों की संख्या <= 8 होनी चाहिए।

इस फाइल में क्या होना चाहिए, इसकी अधिक जानकारी के लिए डॉक्यूमेंटेशन देखिए।

उदाहरण

| Method |      Mean | Allocated |
| -----: | --------: | --------: |
|   Linq | 29.133 ns |      80 B |
|  Array |  4.806 ns |         - |

फाइल: स्टब इम्प्लीमेंटेशन

उद्देश्य: छात्रों को शुरुआत करने की जगह देना।

उपस्थिति: आवश्यक

  • स्टब ऐसा बनाइए कि छात्र को पता चले कि कोड कहाँ जोड़ना है।
  • ऐसी हर सिंटैक्स के लिए स्टब बनाइए जो अभ्यास में नहीं बताई गई है। ज़्यादातर अभ्यासों में इसका मतलब है स्टब फंक्शन/मेथड बनाना।
  • कंपाइल होने वाली भाषाओं में ऐसा कोड रखने के बारे में सोचिए जो कंपाइल हो जाए, क्योंकि भाषा में नए छात्रों के लिए कंपाइलर के संदेश कभी-कभी समझना मुश्किल हो सकता है।
  • कोड जितना हो सके उतना आसान होना चाहिए।
  • सिर्फ वही भाषा-फीचर इस्तेमाल कीजिए जो अभ्यास या उसकी पूर्व-आवश्यकताओं (और उनकी पूर्व-आवश्यकताओं, और इसी तरह) में बताए गए हैं।
  • जब छात्र ब्राउज़र में कोडिंग करता है तो उसे स्टब फाइल दिखाई जाती है, और CLI इस्तेमाल करते समय वह छात्र के फाइल सिस्टम पर डाउनलोड हो जाती है।
  • स्टब इम्प्लीमेंटेशन फाइल के सापेक्ष पाथ .meta/config.json फाइल की "files.solution" key में दिए जाने चाहिए।

उदाहरण

class Lasagna
  def remaining_minutes_in_oven(actual_minutes_in_oven)
    raise NotImplementedError, 'Please implement the Lasagna#remaining_minutes_in_oven method'
  end

  def preparation_time_in_minutes(layers)
    raise NotImplementedError, 'Please implement the Lasagna#preparation_time_in_minutes method'
  end
end

फाइल: टेस्ट

उद्देश्य: यह जाँचना कि हल सही है।

उपस्थिति: आवश्यक

  • टेस्ट में instructions.md फाइल के उदाहरण इस्तेमाल नहीं होने चाहिए।
  • कोड जितना हो सके उतना आसान होना चाहिए।
  • सिर्फ वही भाषा-फीचर इस्तेमाल कीजिए जो अभ्यास की पूर्व-आवश्यकताओं (और उनकी पूर्व-आवश्यकताओं, और इसी तरह) में बताए गए हैं।
  • जब छात्र ब्राउज़र में कोडिंग करता है तो उसे टेस्ट फाइल नहीं दिखाई जाती, पर CLI इस्तेमाल करते समय वह छात्र के फाइल सिस्टम पर डाउनलोड होती है।
  • टेस्ट फाइल के सापेक्ष पाथ .meta/config.json फाइल की "files.test" key में दिए जाने चाहिए।

उदाहरण

require 'minitest/autorun'
require_relative 'lasagna'

class LasagnaTest < Minitest::Test
  def test_remaining_minutes_in_oven
    assert_equal 15, Lasagna.new.remaining_minutes_in_oven(25)
  end

  def test_preparation_time_in_minutes_with_one_layer
    assert_equal 2, Lasagna.new.preparation_time_in_minutes(1)
  end

  def test_preparation_time_in_minutes_with_multiple_layers
    assert_equal 8, Lasagna.new.preparation_time_in_minutes(4)
  end
end

फाइल: एक्ज़ेम्प्लर इम्प्लीमेंटेशन

उद्देश्य: वह लक्ष्य इम्प्लीमेंटेशन देना जिस तक छात्र को पहुँचना है।

उपस्थिति: आवश्यक

  • यह इम्प्लीमेंटेशन वह लक्ष्य कोड है जिस तक हम छात्र को पहुँचते देखना चाहते हैं।
  • फीडबैक लिखते समय मेंटरों को यह कोड "लक्ष्य" के रूप में दिखाया जाएगा
  • इम्प्लीमेंटेशन में सिर्फ वही भाषा-फीचर इस्तेमाल हों जो अभ्यास या उसकी पूर्व-आवश्यकताओं (और उनकी पूर्व-आवश्यकताओं, और इसी तरह) में बताए गए हैं।
  • जब छात्र ब्राउज़र में कोडिंग करता है तो उसे एक्ज़ेम्प्लर फाइल नहीं दिखाई जाती, और CLI इस्तेमाल करते समय वह छात्र के फाइल सिस्टम पर डाउनलोड नहीं होती।
  • हलों या रेप्रेज़ेंटेशनों पर टिप्पणी करते समय मेंटरों को एक्ज़ेम्प्लर फाइल दिखाई जाएगी।
  • उदाहरण इम्प्लीमेंटेशन फाइल के सापेक्ष पाथ .meta/config.json फाइल की "files.exemplar" key में दिए जाने चाहिए।

उदाहरण

class Lasagna
  EXPECTED_MINUTES_IN_OVEN = 40
  PREPARATION_MINUTES_PER_LAYER = 2

  def remaining_minutes_in_oven(actual_minutes_in_oven)
    EXPECTED_MINUTES_IN_OVEN - actual_minutes_in_oven
  end

  def preparation_time_in_minutes(layers)
    layers * PREPARATION_MINUTES_PER_LAYER
  end
end

फाइल: अतिरिक्त फाइलें

उद्देश्य: यह पक्का करना कि टेस्ट चल सकें।

उपस्थिति: अगर डिफ़ॉल्ट फाइलें टेस्ट चलाने के लिए काफी न हों तो आवश्यक

कुछ भाषाओं में टेस्ट चलाने के लिए अतिरिक्त फाइलें चाहिए। जैसे C# की प्रोजेक्ट फाइलें और Node की package.json फाइलें, जिनके बिना टेस्ट चलाना मुमकिन नहीं होगा।

साझा फाइलें

कुछ फाइलें किसी एक अभ्यास की नहीं, बल्कि सारे अभ्यासों पर लागू होती हैं। अधिक जानकारी के लिए डॉक्यूमेंटेशन देखिए।

नामकरण

कॉन्सेप्ट अभ्यासों के नाम उनकी कहानी या विषय पर रखे जाने चाहिए, उनके कॉन्सेप्ट पर नहीं।

अच्छे नामों के उदाहरण:

  • Tim from Marketing
  • Lucian's Luscious Lasagna
  • Calculator Conundrum

नाम जो मान्य नहीं हैं:

  • Booleans: यह कॉन्सेप्ट का नाम है, कहानी का नाम नहीं
  • Exercise #1: अभ्यास कोई कहानी या विषय नहीं होता

किसी अभ्यास को बिना बड़े बदलावों के फोर्क करते समय, जहाँ संभव हो मूल नाम ही रखिए।

स्लग

हर अभ्यास का एक स्लग भी होता है, जो अभ्यास के नाम का नीचे दिए नियमों से बना सामान्यीकृत रूप होता है:

  1. छोटे अक्षर इस्तेमाल कीजिए।
  2. kebab-case इस्तेमाल कीजिए।
  3. लैटिन के अक्षरों और अंकों तथा डैश का इस्तेमाल कीजिए (Regexp: [a-z0-9-]+)
  4. संख्या के अंकों की जगह लिखे हुए शब्दों को प्राथमिकता दीजिए, जब तक कि अंक चुनने की कोई खास वजह न हो (जैसे 2-fer की जगह two-fer)

स्लग के अच्छे उदाहरण:

  • tim-from-marketing
  • lucians-luscious-lasagna
  • calculator-conundrum

स्लग जो मान्य नहीं हैं:

  • TIM-FROM-MARKETING: छोटे अक्षर इस्तेमाल नहीं करता (यानी tim-from-marketing)
  • TimFromMarketing: kebab-case इस्तेमाल नहीं करता (यानी tim-from-marketing)
  • floating-point-numbers: यह कॉन्सेप्ट का नाम है, कहानी का नाम नहीं

प्रस्तुति

ब्राउज़र वाले एडिटर से और CLI से काम करते समय अभ्यास का डॉक्यूमेंटेशन छात्र के सामने अलग-अलग तरीके से रखा जाता है। अधिक जानकारी के लिए यह डॉक्यूमेंट देखिए।

आइकन

हर अभ्यास के साथ एक आइकन होता है। डिफ़ॉल्ट रूप से वही आइकन दिखाया जाता है जिसका नाम अभ्यास के स्लग से मेल खाता है। इसे अभ्यास की .meta/config.json फाइल में icon प्रॉपर्टी देकर बदला जा सकता है।

अगर आप किसी मौजूदा अभ्यास को फोर्क कर रहे हैं, तो उस अभ्यास के लिए शायद पहले से ही आइकन होगा। अगर न हो, तो कृपया website-icons रिपॉज़िटरी में एक issue खोलिए।