مفهوم

مفاهیم همان مواردی هستند که یک برنامه‌نویس برای تسلط بر یک زبان باید آن‌ها را درک کند. مفاهیم از طریق تمرین‌های مفهومی آموزش داده می‌شوند و به‌عنوان پیش‌نیاز برای تمرین‌های مفهومی و عملی به کار می‌روند. مفاهیم هنگام نمایش به دانش‌آموز، روی نقشه‌ی مفاهیم قرار می‌گیرند.

فراداده

فراداده‌ی مفهوم در کلید concepts در پرونده‌ی config.json تعریف می‌شود. این فراداده UUID، slug و موارد بیشترِ مفهوم را تعیین می‌کند.

مثال

{
  "concepts": [
    {
      "uuid": "b9a421b2-c5ff-4213-bd6d-b886da31ea0d",
      "slug": "numbers",
      "name": "Numbers"
    }
  ]
}

پرونده‌ها

هر مفهوم پوشه‌ی مخصوص به خود را درون پوشه‌ی concepts مسیر دارد. اسم پوشه‌ی مفهوم باید با ویژگی slug آن مفهوم، همان‌طور که در پرونده‌ی config.json تعریف شده است، یکسان باشد.

هر مفهوم دو نوع پرونده دارد:

پرونده‌های مستندات

این پرونده‌ها برای کمک به توضیح مفهوم به دانش‌آموز نمایش داده می‌شوند.

• about.md: اطلاعاتی درباره‌ی مفهوم برای دانش‌آموزی فراهم می‌کند که تمرین مفهومی مربوطه را کامل کرده است تا از آن یاد بگیرد و بعداً به آن مراجعه کند (الزامی)
• introduction.md: درآمدی مختصر برای دانش‌آموزی فراهم می‌کند که هنوز تمرین مفهومی مربوطه را کامل نکرده است (الزامی)
• links.json: پیوندهای مفیدی فراهم می‌کند که مطالعه یا اطلاعات بیشتری درباره‌ی یک مفهوم ارائه می‌دهند (الزامی)

پرونده‌های فراداده

این پرونده‌ها به دانش‌آموز نمایش داده نمی‌شوند، بلکه برای تعریف فراداده‌ی مفهوم به کار می‌روند.

• .meta/config.json: شامل اطلاعات فراداده درباره‌ی مفهوم است (الزامی)

مثال

concepts
└── numbers
    ├── .meta
    |   └── config.json
    ├── about.md
    ├── introduction.md
    └── links.json

پرونده: about.md

هدف: ارائه‌ی اطلاعاتی دقیق‌تر درباره‌ی مفهوم به دانش‌آموزی که تمرین مفهومی مربوطه را کامل کرده است، تا از آن یاد بگیرد و بعداً به آن مراجعه کند.

وجود: الزامی

پس از کامل کردن تمرین مفهومی مربوطه (که به آن «یادگیری» یک مفهوم هم می‌گویند)، صفحه‌ی مفهوم به‌جای پرونده‌ی introduction.md محتوای پرونده‌ی about.md را نمایش می‌دهد. پرونده‌ی about.md باید به دانش‌آموزان اطلاعات جامعی درباره‌ی آنچه برای مسلط شدن بر مفهوم باید بدانند ارائه دهد. این پرونده دست‌کم باید همه‌ی اطلاعاتی را در خود داشته باشد که در سند introduction.md مفاهیم معرفی می‌شود.

اگر مفهوم نحوه‌ی نگارش تازه‌ای را معرفی می‌کند، باید نمونه‌های آن هم آورده شود. دانش‌آموز نباید برای به دست آوردن دانشی که این پرونده می‌خواهد منتقل کند، مجبور باشد دنبال پیوندهای زیادی برود. در عوض، about.md باید اطلاعات کافی داشته باشد تا در بافت خودش قابل فهم باشد.

پرونده‌ی about.md به حوزه‌ی تمرین مفهومی مربوطه محدود نیست. این محتوا می‌تواند مستلزم دانستن مفاهیم دیگری باشد که بعداً معرفی می‌شوند. اگر به مفاهیم دیگری اشاره می‌شود، باید به درآمدهای مربوط به آن‌ها پیوند داده شود (برای جزئیات، پیونددهی درونی را ببینید).

در ادامه چند نمونه از مواردی که می‌توان به آن‌ها پرداخت آمده است.

• کاربردهای رایج یک مفهوم
• دام‌های رایج در استفاده از یک مفهوم (مثلاً توجه نکردن به ایمنی نخ‌ها)
• محدودیت‌هایی در استفاده که ممکن است برنامه‌نویس غافل را به دام بیندازد
• رویکردهای جایگزینی که در مفاهیم دیگر بررسی می‌شوند (مثلاً مفهوم بازگشت ممکن است اشاره کند که مفهوم توابع مرتبه‌بالا رویکرد جایگزینی برای مسائل مشابه ارائه می‌دهد)
• سازش‌هایی که برای آسان‌تر کردن یادگیری یا هماهنگی با محیط Exercism انجام می‌شود، مثلاً چند کلاس در یک پرونده
• ویژگی‌های مشابهی که ممکن است مفهوم با آن‌ها اشتباه گرفته شود
• ویژگی‌های کارایی و مصرف حافظه، زمانی که موضوعی رایج در آن زبان باشد
• در متن به هیچ تمرینی اشاره نکنید، چون این پرونده خارج از بافت یک تمرین نمایش داده می‌شود.

هدف پرونده‌ی about.md این نیست که مجموعه‌ی کاملی از اطلاعات درباره‌ی مفهوم ارائه دهد. برای نمونه، زبانی را در نظر بگیرید که ویژگی‌های قدیمی‌تری دارد که برنامه‌نویسان باتجربه (و شاید حتی مستندات/مشخصات رسمی) توصیه می‌کنند دیگر از آن‌ها استفاده نشود. پرداختن به جزئیات چنین ویژگی‌هایی خارج از حوزه‌ی پرونده‌ی about.md است، چون برای کسب تسلط مرتبط نیستند. با این حال، نگه‌دارندگان ممکن است تصمیم بگیرند اگر احتمال دارد دانش‌آموز معمولاً در دنیای واقعی با آن استانداردهای قدیمی روبه‌رو شود، بلوک کوتاهی برای اشاره به آن‌ها اضافه کنند. البته این بلوک باید به‌عنوان چنین بلوکی مشخص شود.

پرونده‌ی about.md باید ساختار روشنی داشته باشد، به‌ویژه وقتی حجم زیادی از اطلاعات را در خود دارد. در آینده از علامت‌گذاری بخش‌ها به‌عنوان «موضوعات پیشرفته» هم پشتیبانی خواهد شد تا بدون سنگین کردن بار دیگران، آن‌ها را به دانش‌آموزان علاقه‌مند نشان دهد.

مثال

# About

There are two different kinds of numbers in Elixir - integers and floats.

Floats are numbers with one or more digits behind the decimal separator. They use the 64-bit double precision floating-point format.

```elixir
float = 3.45
# => 3.45
```

Elixir also supports the scientific notation for floats.

```elixir
1.25e-2
# => 0.0125
```

## Rounding errors

Floats are infamous for their rounding errors.

```elixir
0.1 + 0.2
# => 0.30000000000000004
```

However, those kind of errors are not specific to Elixir. They happen in all programming languages. This is because all data on our computers is stored and processed as binary code. In binary, only fractions whose denominator can be expressed as `2^n` (e.g. `1/4`, `3/8`, `5/16`) can be expressed exactly. Other fractions are expressed as estimations.

```elixir
# 3/4
Float.ratio(0.75)
# => {3, 4}

# 3/5
Float.ratio(0.6)
# => {5404319552844595, 9007199254740992}
```

You can learn more about this problem at [0.30000000000000004.com][0.30000000000000004.com]. The [Float Toy page][evanw.github.io-float-toy] has a nice, graphical explanation how a floating-point number's bits are converted to an actual floating-point value.

پرونده: introduction.md

هدف: ارائه‌ی درآمدی مختصر به دانش‌آموزی که هنوز تمرین مفهومی مربوطه را کامل نکرده است.

وجود: الزامی

این پرونده در صورتی نمایش داده می‌شود که دانش‌آموز هنوز تمرین مفهومی مربوطه را کامل نکرده باشد. این پرونده باید درآمدی مختصر از مفهوم ارائه دهد.

• فقط اطلاعاتی که برای درک مبانی مفهوم لازم است باید ارائه شود. اطلاعات اضافی باید برای سند about.md باقی بماند.
• پیوندها باید کم و تنها در صورت نیاز به کار روند. گرچه پیوندی که موضوعی پیچیده مثل بازگشت را توضیح می‌دهد می‌تواند مفید باشد، برای بیشتر مفاهیم پیوندها اطلاعاتی بیش از نیاز ارائه می‌دهند، پس هدف باید توضیح مختصر و درون‌متنی باشد.
• باید از اصطلاحات فنی درست استفاده شود تا دانش‌آموز بتواند به‌راحتی اطلاعات بیشتری جست‌وجو کند.
• نمونه‌های کد فقط باید برای معرفی نحوه‌ی نگارش تازه به کار روند (دانش‌آموزان نباید لازم باشد برای نمونه‌های نحوه‌ی نگارش در وب جست‌وجو کنند). در موارد دیگر، به‌جای کد توضیح یا پیوند ارائه دهید.
• در متن به هیچ تمرینی اشاره نکنید، چون این پرونده خارج از بافت یک تمرین نمایش داده می‌شود.

مثال

# Introduction

One of the key aspects of working with numbers in C# is the distinction between integers and floating-point numbers (numbers with zero or more digits after the decimal separator).

The two most commonly used numeric types in C# are `int` (a 32-bit integer) and `double` (a 64-bit floating-point number).

```csharp
int i = 123;
double d = 54.29;
```

پرونده: links.json

هدف: ارائه‌ی پیوندهای مفیدی که مطالعه یا اطلاعات بیشتری درباره‌ی یک مفهوم فراهم می‌کنند.

وجود: الزامی

این‌ها می‌توانند مستندات رسمی، یک آموزش عالی و مانند این‌ها باشند. این پیوندها جای پیوندهای بافت‌محورتر درون پرونده‌ی about.md یک مفهوم را نمی‌گیرند، بلکه مجموعه‌ای سریع از نقاط مرجع کلی برای دانش‌آموز فراهم می‌کنند.

هر پیوند باید شامل این فیلدها باشد:

• url: نشانی که پیوند به آن داده می‌شود.
• description: توضیحی از پیوند که به‌عنوان متن پیوند نمایش داده می‌شود.

پیوندها می‌توانند به‌صورت اختیاری فیلد icon_url هم داشته باشند که می‌توان از آن برای سفارشی‌سازی نمادی که هنگام نمایش پیوند نشان داده می‌شود استفاده کرد. اگر مشخص نشود، نماد به‌طور پیش‌فرض favicon است.

[
  {
    "url": "https://docs.microsoft.com/en-us/dotnet/csharp/tutorials/intro-to-csharp/numbers-in-csharp-local",
    "description": "Numbers in C#"
  },
  {
    "url": "https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/integral-numeric-types",
    "description": "Integral numeric types",
    "icon_url": "http://test.org/icon.png"
  }
]

---

پرونده: .meta/config.json

هدف: شامل اطلاعات فراداده درباره‌ی مفهوم است.

وجود: الزامی

این پرونده اطلاعات فراداده‌ی مفهوم را در خود دارد:

• authors: شناسه‌ی کاربری GitHub نویسنده(های) مفهوم (الزامی)
  • اگر بازبینی‌های بازبین‌ها مفهوم را به‌طور چشمگیری تغییر داده باشد، آن‌ها را هم شامل می‌شود (تا حدی که حس شود «با هم به آنجا رسیدید»)
• contributors: شناسه‌ی کاربری GitHub مشارکت‌کننده(های) مفهوم (اختیاری)
  • اگر بازبینی‌هایشان معنادار، قابل اقدام یا اقدام‌شده باشد، بازبین‌ها را هم شامل می‌شود.
• blurb: توضیحی کوتاه از این مفهوم. طول آن باید حداکثر ۳۵۰ باشد. از Markdown پشتیبانی نمی‌شود (الزامی)

اگر کسی هم نویسنده و هم مشارکت‌کننده است، اسم آن شخص را فقط به‌عنوان نویسنده فهرست کنید.

مثال

{
  "authors": ["FSharpForever"],
  "contributors": ["IWantToHelp"],
  "blurb": "F# has two types of numbers: integers and floating-point numbers."
}

توجه کنید:

• ترتیب نویسندگان و مشارکت‌کنندگان مهم نیست و معنایی به آن داده نمی‌شود.