تمرین عملی

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

علاقه‌مندید اولین تمرین عملی خود را به یک ترک اضافه کنید؟ نگاهی به مستندات افزودن تمرین عملی بیندازید یا ویدیوی آموزشی ما را تماشا کنید 👇

Note

می‌توانید با اجرای دستورهای زیر از پوشه‌ی ریشه‌ی ترک، به‌سرعت یک تمرین عملی تازه بسازید:

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

برای اطلاعات بیشتر، مستندات configlet create را ببینید.

فراداده

فراداده‌ی تمرین عملی در کلید exercises.practice در فایل config.json تعریف می‌شود. این فراداده، UUID، اسلاگ و موارد بیشتر تمرین را مشخص می‌کند.

مثال

{
  "exercises": {
    "practice": [
      {
        "uuid": "8ba15933-29a2-49b1-a9ce-70474bad3007",
        "slug": "leap",
        "name": "Leap",
        "practices": ["if-statements", "numbers", "operator-precedence"],
        "prerequisites": ["if-statements", "numbers"],
        "difficulty": 1
      }
    ]
  }
}

`practices`

کلید practices باید اسلاگ مفاهیمی را فهرست کند که این تمرین عملی به دانشجو اجازه می‌دهد فعالانه آن‌ها را تمرین کند.

این‌ها در رابط کاربری به شکل «این مفهوم را در این تمرین‌ها تمرین کنید: TwoFer، Leap و غیره» نمایش داده می‌شوند
تلاش کنید برای هر مفهوم، ۳ تا ۸ تمرین انتخاب کنید که آن مفهوم را تمرین می‌دهند.
تلاش کنید حداقل دو تمرین انتخاب کنید که به کسی اجازه دهند مبانی یک مفهوم را تمرین کند.
برخی مفاهیم بسیار رایج‌اند (برای مثال strings). در چنین مواردی توصیه می‌کنیم چند تمرین خوب انتخاب کنید که افراد را به فکر کردن درباره‌ی آن مفاهیم به شیوه‌های جالب وادارند. برای مثال، تمرین‌هایی که به UTF-8، اتصال رشته‌ها، برشماری کاراکترها و مواردی از این دست نیاز دارند، همه نمونه‌های خوبی هستند.

`prerequisites`

کلید prerequisites مفاهیمی را فهرست می‌کند که دانشجو باید تکمیل کرده باشد تا به این تمرین عملی دسترسی پیدا کند.

این‌ها در رابط کاربری به شکل «برای باز کردن قفل TwoFer، رشته‌ها را یاد بگیرید» نمایش داده می‌شوند
باید همه‌ی مفاهیمی را شامل شود که دانشجو باید پوشش داده باشد تا بتواند تمرین را به دست‌کم یک شیوه‌ی اصطلاحی کامل کند. برای مثال، برای تمرین TwoFer در Ruby، پیش‌نیازها ممکن است شامل strings، optional-params و implicit-return باشد.
برای تمرین‌هایی که می‌توان آن‌ها را با مفاهیم جایگزین کامل کرد (مثلاً تمرینی که با loops یا recursion حل می‌شود)، نگهدارنده باید همان رویکردی را انتخاب کند که می‌خواهد با آن قفل تمرین را باز کند، با در نظر گرفتن مسیر دانشجو در طول ترک. برای مثال، در نمونه‌ی حلقه/بازگشت، ممکن است فکر کنند این تمرین تمرین خوبی برای شروع loops است یا شاید ترجیح دهند آن را برای بعد بگذارند تا recursion را آموزش دهند. همچنین می‌توانند از تحلیلگر استفاده کنند تا دانشجو را به امتحان کردن رویکرد جایگزین ترغیب کنند: «آفرین که این را با حلقه‌ها حل کردید. ممکن است بخواهید آن را با استفاده از Recursion هم امتحان کنید.»

فایل‌ها

هر تمرین عملی پوشه‌ی خودش را درون پوشه‌ی exercises/practice ترک دارد. نام پوشه‌ی تمرین عملی باید با ویژگی slug تمرین عملی مطابقت داشته باشد، همان‌طور که در فایل config.json تعریف شده است.

یک تمرین عملی چهار نوع فایل دارد:

فایل‌های مستندات

این فایل‌ها به دانشجو ارائه می‌شوند تا به توضیح تمرین کمک کنند.

.docs/introduction.md: محیط و پیشینه‌ی تمرین را معرفی می‌کند (اختیاری)
.docs/introduction.append.md: متن مقدمه‌ی اضافی که پس از مقدمه‌ی موجود افزوده می‌شود (اختیاری)
.docs/instructions.md: دستورهای تمرین را ارائه می‌دهد (الزامی)
.docs/instructions.append.md: متن مقدمه‌ی اضافی که پس از دستورهای موجود افزوده می‌شود (اختیاری)
.docs/hints.md: راهنمایی‌هایی به دانشجو ارائه می‌دهد تا کمکش کند در تمرین گیر نکند (اختیاری)

فایل‌های فراداده

این فایل‌ها به دانشجو ارائه نمی‌شوند، بلکه برای تعریف فراداده‌ی تمرین به کار می‌روند.

.meta/config.json: شامل اطلاعات فراداده درباره‌ی تمرین است (الزامی)
.meta/design.md: طراحی تمرین را توصیف می‌کند (اختیاری)
.meta/tests.toml: شامل اطلاعاتی درباره‌ی این است که چه تست‌هایی پیاده‌سازی شده‌اند (اختیاری)

فایل‌های رویکرد

این فایل‌ها رویکردهای تمرین را توصیف می‌کنند.

.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
└── practice
    └── isogram
        ├── .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
        |   ├── tests.toml
        |   └── Example.cs (example implementation)
        ├── Isogram.cs (stub implementation)
        └── IsogramTests.cs (tests)

فایل: `.docs/introduction.md`

هدف: معرفی محیط و پیشینه‌ی تمرین به دانشجو.

حضور: الزامی است اگر تمرین، یک تمرین Problem Specifications با فایل introduction.md را پیاده‌سازی کند

اگر تمرین یک تمرین Problem Specifications را پیاده‌سازی می‌کند، محتوای این فایل باید با فایل introduction.md آن تمرین Problem Specifications مطابقت داشته باشد. configlet این قابلیت را دارد که محتوای این فایل را به‌طور خودکار همگام‌سازی کند.

اگر تمرین بر پایه‌ی یک تمرین Problem Specifications نیست، موارد زیر را در نظر بگیرید:

ما برای ایمن بودن محتوای Exercism برای همه ارزش زیادی قائل هستیم و به همین دلیل هنگام تصمیم‌گیری درباره‌ی مناسب بودن یا نبودن داستان‌ها، اغلب جانب احتیاط را رعایت می‌کنیم. هرچند در مورد آنچه ادغام می‌کنیم دقت می‌کنیم، می‌دانیم که آگاه بودن از آنچه ممکن است مشکل‌دار تلقی شود دشوار است، بنابراین همیشه فرض می‌کنیم شما با حسن نیت عمل می‌کنید و تلاش می‌کنیم در بازبینی، هر مشکلی را به شیوه‌ای غیرتقابلی پیدا کنیم. اگر می‌خواهید داستانی را با ما بررسی کنید، لطفاً @exercism/leadership را منشن کنید تا با هم به آن نگاه کنیم. در ادامه چند نکته‌ی راهنما آمده است:

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

مثال

# Introduction

Bob is a lackadaisical teenager. In conversation, his responses are very limited.

فایل: `.docs/introduction.append.md`

هدف: متن مقدمه‌ی اضافی که پس از مقدمه‌ی موجود افزوده می‌شود.

حضور: اختیاری

در برخی موارد (کمیاب)، ممکن است بخواهید فایل introduction.md تمرین را گسترش دهید، برای مثال زمانی که تمرین تست‌هایی را پیاده‌سازی کرده است که دستورهای موجود آن‌ها را پوشش نمی‌دهند.

ترکی که نمی‌خواهد Bob از پیام‌های غیر ASCII پشتیبانی کند، ممکن است موارد زیر را اضافه کند:

# Introduction append

## Note

As part of his teenage rebellion, Bob has decided to only communicate using ASCII.

فایل‌های افزودنی باید با یک سرصفحه‌ی H1 شروع شوند. این سرصفحه نمایش داده نمی‌شود، اما باید همچنان وجود داشته باشد. سرصفحه‌ی H1 اغلب با یک سرصفحه‌ی H2 دنبال می‌شود که به جدا کردن محتوای عمومی از محتوای مخصوص ترک کمک می‌کند.

فایل: `.docs/instructions.md`

هدف: ارائه‌ی دستورهای تمرین.

حضور: الزامی

اگر تمرین یک تمرین Problem Specifications را پیاده‌سازی می‌کند، محتوای این فایل باید با فایل instructions.md آن تمرین Problem Specifications مطابقت داشته باشد (یا فایل description.md اگر فایل instructions.md وجود ندارد). configlet این قابلیت را دارد که محتوای این فایل را به‌طور خودکار همگام‌سازی کند.

اگر تمرین بر پایه‌ی یک تمرین Problem Specifications نیست، موارد زیر را در نظر بگیرید:

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

مثال

# Instructions

Bob answers 'Sure.' if you ask him a question, such as "How are you?".

He answers 'Whoa, chill out!' if you YELL AT HIM (in all capitals).

He answers 'Calm down, I know what I'm doing!' if you yell a question at him.

He says 'Fine. Be that way!' if you address him without actually saying anything.

He answers 'Whatever.' to anything else.

فایل: `.docs/instructions.append.md`

هدف: متن دستورهای اضافی که پس از دستورهای موجود افزوده می‌شود.

حضور: اختیاری

در برخی موارد (کمیاب)، ممکن است بخواهید فایل instructions.md تمرین را گسترش دهید، برای مثال زمانی که تمرین تست‌هایی را پیاده‌سازی کرده است که دستورهای موجود آن‌ها را پوشش نمی‌دهند.

# Instructions append

## Note

Bob's conversational partner is a purist when it comes to written communication and always follows normal rules regarding sentence punctuation in English.

فایل: `.docs/hints.md`

هدف: ارائه‌ی راهنمایی به دانشجو تا کمکش کند در تمرین گیر نکند.

حضور: اختیاری

اگر دانشجو گیر کند، به او اجازه می‌دهیم روی دکمه‌ای کلیک کند که درخواست راهنمایی می‌کند و بخش مربوطه‌ی فایل را نشان می‌دهد.
راهنمایی‌ها باید به‌صورت فهرست نقطه‌ای زیر سرصفحه‌ها بیایند.
راهنمایی‌ها باید کافی باشند تا تقریباً هر دانشجویی را از بن‌بست بیرون بیاورند.
راهنمایی‌ها نباید راه‌حل را کامل بنویسند، بلکه باید به منبعی اشاره کنند که راه‌حل را توصیف می‌کند (مثلاً پیوند دادن به مستندات تابعی که باید استفاده شود).
راهنمایی‌ها ممکن است از نمونه‌کدها برای توضیح مفاهیم استفاده کنند، اما نه برای ترسیم راه‌حل. مثلاً در یک تمرین فهرست، ممکن است نمونه‌ای نشان دهند که یک تابع فهرست مشخص چطور کار می‌کند، اما نه به شکلی که مستقیماً قابل کپی‌برداری در راه‌حل باشد.
راهنمایی‌ها باید به‌صورت یک فهرست Markdown زیر سرصفحه‌ی ## General ظاهر شوند.
اگر راهنمایی‌ای وجود ندارد، باید آن سرصفحه حذف شود.

دیدن راهنمایی‌ها یک مسیر «توصیه‌شده» نیست و ما (به ملایمت) از استفاده از آن دلسرد می‌کنیم، مگر اینکه دانشجو بدون آن نتواند پیش برود. بنابراین ارزش دارد در نظر بگیرید که دانشجویی که آن را می‌خواند کمی گیج یا درمانده و شاید ناامید باشد.

مثال

## General

- There are many [built-in methods][integers] to simplify working with integers.

[integers]: https://ruby-doc.org/core-2.7.0/Integer.html

فایل: .meta/design.md

هدف: توصیف طراحی تمرین.

حضور: اختیاری

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

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

مثال

# Design

## Goal

The goal of this exercise is help students practice how to work with strings.

## Notes

This exercise does not contain any error handling tests.

فایل: `.meta/config.json`

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

حضور: الزامی

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

authors: نام کاربری GitHub نویسنده(گان) تمرین (اختیاری)
- شامل بازبین‌ها در صورتی که بازبینی‌شان تمرین را به‌طور قابل‌توجهی تغییر دهد (تا حدی که حس شود «با هم به نتیجه رسیدید»)
contributors: نام کاربری GitHub مشارکت‌کننده(گان) تمرین (اختیاری)
- شامل بازبین‌ها در صورتی که بازبینی‌هایشان معنادار/قابل اجرا/اجرا شده باشد.
files: مکان فایل‌های استفاده‌شده در این تمرین، نسبت به پوشه‌ی تمرین (الزامی)
- solution: فایل(های) پیاده‌سازی اسکلتی (الزامی)
- test: فایل(های) تست (الزامی)
- example: فایل(های) پیاده‌سازی نمونه (الزامی)
- editor: فایل‌های اضافی که در ویرایشگر به‌صورت فقط‌خواندنی نشان داده می‌شوند (اختیاری)
- invalidator: فایل‌هایی که وقتی تغییر کنند، باعث می‌شوند یک راه‌حل قدیمی شود (اختیاری)
language_versions نیازمندی‌های نسخه‌ی زبان (اختیاری)
blurb: توضیح کوتاهی از این تمرین. طول آن باید حداکثر ۳۵۰ باشد. Markdown پشتیبانی نمی‌شود (الزامی)
source: منبعی که این تمرین بر پایه‌ی آن است (اختیاری)
source_url: URL منبعی که این تمرین بر پایه‌ی آن است (اختیاری)
test_runner: مشخص می‌کند که آیا راه‌حل‌های این تمرین باید در اجراکننده‌ی تست تست شوند یا نه. اگر مشخص نشود، به‌طور پیش‌فرض true است. (اختیاری)
representer: اطلاعات فراداده‌ی مرتبط با نحوه‌ی پردازش این فایل توسط representer (اختیاری)
- version: یک عدد صحیح برای نسخه‌ی representer که برای تمرین استفاده می‌شود (در صورت وجود کلید والد، الزامی)
icon: اسلاگ آیکون (به فهرست کامل آیکون‌ها مراجعه کنید). اگر مشخص نشود، از اسلاگ تمرین استفاده می‌شود (اختیاری)
custom: هر داده‌ی غیراستاندارد و مخصوص تمرین. می‌توان از آن برای سفارشی‌سازی رفتار ابزارهای ترک به‌ازای هر تمرین استفاده کرد (اختیاری)

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

مثال

{
  "authors": ["FSharpForever"],
  "files": {
    "solution": ["Bob.fs"],
    "test": ["BobTests.fs"],
    "example": [".meta/Example.fs"]
  },
  "blurb": "Bob is a lackadaisical teenager. In conversation, his responses are very limited"
}

توجه کنید که:

ترتیب نویسندگان و مشارکت‌کنندگان مهم نیست و معنایی ندارد.
language_versions رشته‌ای آزاد است که ترک‌ها می‌توانند آزادانه آن را به هر شکلی که می‌خواهند استفاده و تفسیر کنند.

فایل: .meta/tests.toml

هدف: شامل اطلاعاتی درباره‌ی این است که چه تست‌هایی پیاده‌سازی شده‌اند.

حضور: اختیاری

این فایل شامل اطلاعاتی درباره‌ی این است که چه تست‌هایی پیاده‌سازی می‌شوند، به شرط آنکه تمرین تست‌هایی در فایل canonical-data.json خود در مخزن problem-specifications تعریف کرده باشد.

این فایل وجود دارد تا به نگهدارندگان کمک کند پیگیری کنند چه تست‌هایی پیاده‌سازی شده‌اند و (به‌صورت اختیاری) مستند کنند چرا تست خاصی پیاده‌سازی نشده است. همچنین می‌توان از آن برای شناسایی تست‌های پیاده‌سازی‌نشده استفاده کرد.

ابزار configlet به‌روزرسانی/همگام‌سازی این فایل با داده‌های مخزن problem-specifications را از طریق دستور configlet sync انجام می‌دهد. هنگام همگام‌سازی، configlet برای هر تست پیاده‌سازی‌نشده می‌پرسد که آن تست گنجانده شود یا نه.

مثال

# This is an auto-generated file.
#
# Regenerating this file via `configlet sync` will:
# - Recreate every `description` key/value pair
# - Recreate every `reimplements` key/value pair, where they exist in problem-specifications
# - Remove any `include = true` key/value pair (an omitted `include` key implies inclusion)
# - Preserve any other key/value pair
#
# As user-added comments (using the # character) will be removed when this file
# is regenerated, comments can be added via a `comment` key.

[3e5c30a8-87e2-4845-a815-a49671ade970]
description = "empty strand"

[a0ea42a6-06d9-4ac6-828c-7ccaccf98fec]
description = "can count one nucleotide in single-character input"

[eca0d565-ed8c-43e7-9033-6cefbf5115b5]
description = "strand with repeated nucleotide"

[40a45eac-c83f-4740-901a-20b22d15a39f]
description = "strand with multiple nucleotides"

[b4c47851-ee9e-4b0a-be70-a86e343bd851]
description = "strand with invalid nucleotides"
include = false
comment = "error handling omitted on purpose"

فایل: `.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: یک UUID نسخه‌ی ۴ که رویکرد را به‌طور یکتا مشخص می‌کند. UUID باید هم درون ترک و هم در میان همه‌ی ترک‌ها یکتا باشد و هرگز تغییر نکند
- slug: اسلاگ رویکرد که رشته‌ای با حروف کوچک و به سبک kebab-case است. اسلاگ باید در میان همه‌ی اسلاگ‌های رویکرد درون ترک یکتا باشد. طول آن باید حداکثر ۲۵۵ باشد.
- title: عنوان رویکرد. طول آن باید حداکثر ۲۵۵ باشد.
- blurb: توضیح کوتاهی از این رویکرد. طول آن باید حداکثر ۳۵۰ باشد. 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 یک تمرین نشان داده می‌شود.

تعداد خطوط آن باید حداکثر ۸ باشد.

برای اطلاعات بیشتر درباره‌ی اینکه چه چیزی باید در این فایل باشد، مستندات را ببینید.

مثال

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: یک UUID نسخه‌ی ۴ که مقاله را به‌طور یکتا مشخص می‌کند. UUID باید هم درون ترک و هم در میان همه‌ی ترک‌ها یکتا باشد و هرگز تغییر نکند
- slug: اسلاگ مقاله که رشته‌ای با حروف کوچک و به سبک kebab-case است. اسلاگ باید در میان همه‌ی اسلاگ‌های مقاله درون ترک یکتا باشد. طول آن باید حداکثر ۲۵۵ باشد.
- title: عنوان مقاله. طول آن باید حداکثر ۲۵۵ باشد.
- blurb: توضیح کوتاهی از این مقاله. طول آن باید حداکثر ۳۵۰ باشد. 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 یک تمرین نشان داده می‌شود.

تعداد خطوط آن باید حداکثر ۸ باشد.

برای اطلاعات بیشتر درباره‌ی اینکه چه چیزی باید در این فایل باشد، مستندات را ببینید.

مثال

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

فایل: پیاده‌سازی اسکلتی

هدف: فراهم کردن نقطه‌ی شروعی برای دانشجوها.

حضور: الزامی

اسکلت را طوری طراحی کنید که دانشجو بداند کد را کجا اضافه کند.
برای زبان‌های کامپایل‌شونده، در نظر بگیرید که کدی قابل کامپایل داشته باشید، چون پیام‌های کامپایلر گاهی برای دانشجوهای تازه‌وارد به زبان دشوار قابل درک است.
کد باید تا حد ممکن ساده باشد.
فقط از ویژگی‌های زبانی استفاده کنید که توسط پیش‌نیازها (و پیش‌نیازهای آن‌ها و به همین ترتیب) معرفی شده‌اند.
فایل اسکلت هنگام کدنویسی در مرورگر به دانشجو نشان داده می‌شود و هنگام استفاده از CLI روی سیستم فایل دانشجو دانلود می‌شود.
مسیرهای نسبی به فایل(های) پیاده‌سازی اسکلتی باید در کلید "files.solution" فایل .meta/config.json مشخص شوند.

مثال

using System;

public static class Isogram
{
    public static bool IsIsogram(string word)
    {
        throw new NotImplementedException("You need to implement this function.");
    }
}

فایل: تست‌ها

هدف: بررسی درستی یک راه‌حل.

حضور: الزامی

کد باید تا حد ممکن ساده باشد.
فقط از ویژگی‌های زبانی استفاده کنید که توسط پیش‌نیازهای تمرین (و پیش‌نیازهای آن‌ها و به همین ترتیب) معرفی شده‌اند.
فایل تست‌ها هنگام کدنویسی در مرورگر به دانشجو نشان داده می‌شود و هنگام استفاده از CLI روی سیستم فایل دانشجو دانلود می‌شود.
Exercism ترجیح می‌دهد تمرین‌های عملی از طریق توسعه‌ی تست‌محور کامل شوند. برای دستیابی به این هدف، دو گزینه وجود دارد:
- اجراکننده‌ی تست باید تست‌ها را به ترتیبی که در فایل تعریف شده اجرا کند و مجموعه‌ی تست باید در نخستین شکست متوقف شود؛ یا
- همه‌ی تست‌ها به‌جز اولی باید به‌طور پیش‌فرض نادیده گرفته شوند.
مسیرهای نسبی به فایل(های) تست باید در کلید "files.test" فایل .meta/config.json مشخص شوند.

مثال

using Xunit;

public class IsogramTest
{
    [Fact]
    public void Empty_string() =>
        Assert.True(Isogram.IsIsogram(""));

    [Fact(Skip = "Remove this Skip property to run this test")]
    public void Isogram_with_only_lower_case_characters() =>
        Assert.True(Isogram.IsIsogram("isogram"));

    [Fact(Skip = "Remove this Skip property to run this test")]
    public void Word_with_one_duplicated_character() =>
        Assert.False(Isogram.IsIsogram("eleven"));
}

فایل: پیاده‌سازی نمونه

هدف: ارائه‌ی پیاده‌سازی نمونه‌ای که همه‌ی تست‌ها را پاس می‌کند.

حضور: الزامی

این پیاده‌سازی برای بررسی این استفاده می‌شود که پیاده‌سازی‌ای وجود دارد که تست‌ها را پاس کرده است. عمداً همان کد هدفی نیست که می‌خواهیم دانشجو به دنبال آن باشد.
هر ترک باید در تنظیمات یکپارچه‌سازی مداوم خود بررسی کند که پیاده‌سازی نمونه تست‌ها را پاس می‌کند.
این کد به مربی‌ها نشان داده نمی‌شود.
فایل نمونه هنگام کدنویسی در مرورگر به دانشجو نشان داده نمی‌شود و هنگام استفاده از CLI روی سیستم فایل دانشجو دانلود نمی‌شود.
مسیرهای نسبی به فایل(های) پیاده‌سازی نمونه باید در کلید "files.example" فایل .meta/config.json مشخص شوند.

مثال

using System.Linq;

public static class Isogram
{
    public static bool IsIsogram(string word)
    {
        var lowerCaseLetters = word.ToLower().Where(char.IsLetter).ToList();
        return lowerCaseLetters.Distinct().Count() == lowerCaseLetters.Count;
    }
}

فایل: فایل‌های اضافی

هدف: فایل‌های اضافی پروژه، ساخت یا پشتیبان که برای اجرای تست‌ها لازم است.

حضور: در صورت کافی نبودن فایل‌های پیش‌فرض برای اجرای تست‌ها، الزامی است

برخی زبان‌ها برای اجرای تست‌ها به فایل‌های اضافی نیاز دارند. نمونه‌ی این‌ها فایل‌های پروژه‌ی C# و فایل‌های package.json در Node است که بدون آن‌ها اجرای تست‌ها ممکن نخواهد بود.

فایل‌های مشترک

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

ارائه

در نحوه‌ی ارائه‌ی مستندات تمرین به دانشجو هنگام استفاده از ویرایشگر مرورگر در مقابل استفاده از CLI تفاوت وجود دارد. برای اطلاعات بیشتر این سند را ببینید.

آیکون

هر تمرین یک آیکون همراه دارد. به‌طور پیش‌فرض، آیکون نمایش‌داده‌شده همانی است که نامش با اسلاگ تمرین مطابقت دارد. می‌توان با مشخص کردن ویژگی icon در فایل .meta/config.json تمرین، این را بازنویسی کرد.

اگر تمرینی را از فراداده‌ی problem-specifications پیاده‌سازی می‌کنید، احتمالاً از قبل آیکونی برای آن تمرین وجود دارد. اگر نه، لطفاً یک ایشو در مخزن website-icons باز کنید.

مسیرهای زبان

با Jiki کدنویسی یاد بگیرید

سفر شما

علاقه‌مندی‌های شماجدید

مزایای Exercism

ویدیوهای جامعه

مجموعه‌ی معرفی‌های کوتاه

مصاحبه‌ها و داستان‌ها

Discord

انجمن

شروع کار

منتورینگ

مستندات

مشارکت‌کنندگان

مترجمانجدید

حمایت مالی

درباره‌ی Exercism

تأثیر ما

همگام‌ساز GitHubجدید

Insiders

تمرین عملی

فراداده

مثال

practices

prerequisites

فایل‌ها

فایل‌های مستندات

فایل‌های فراداده

فایل‌های رویکرد

فایل‌های مقاله

فایل‌های تمرین

مثال

فایل: .docs/introduction.md

مثال

فایل: .docs/introduction.append.md

فایل: .docs/instructions.md

مثال

فایل: .docs/instructions.append.md

فایل: .docs/hints.md

مثال

فایل: .meta/design.md

مثال

فایل: .meta/config.json

مثال

فایل: .meta/tests.toml

مثال

فایل: .approaches/introduction.md

مثال

فایل: .approaches/config.json

مثال

فایل: .approaches/<approach-slug>/content.md

مثال

فایل: .approaches/<approach-slug>/snippet.txt

مثال

فایل: .article/config.json

مثال

فایل: .articles/<article-slug>/content.md

مثال

فایل: .articles/<article-slug>/snippet.txt

مثال

فایل: پیاده‌سازی اسکلتی

مثال

فایل: تست‌ها

مثال

فایل: پیاده‌سازی نمونه

مثال

فایل: فایل‌های اضافی

فایل‌های مشترک

ارائه

آیکون

`practices`

`prerequisites`

فایل: `.docs/introduction.md`

فایل: `.docs/introduction.append.md`

فایل: `.docs/instructions.md`

فایل: `.docs/instructions.append.md`

فایل: `.docs/hints.md`

فایل: `.meta/config.json`

فایل: `.approaches/introduction.md`

فایل: `.approaches/config.json`

فایل: `.approaches/<approach-slug>/content.md`

فایل: `.approaches/<approach-slug>/snippet.txt`

فایل: `.article/config.json`

فایل: `.articles/<article-slug>/content.md`

فایل: `.articles/<article-slug>/snippet.txt`