شیوه‌نامه‌ی Exercism

این سند به‌عنوان راهنمای سبکی برای زبان و واژه‌گزینی به‌کاررفته در تمرین‌ها عمل می‌کند.

کاربرد

این قواعد باید در همه‌ی تمرین‌ها رعایت شوند. می‌توان توضیحات و موارد آزمون موجود را طوری به‌روزرسانی کرد که با آن‌ها هم‌خوان شوند، بی‌آنکه به موارد آزمون «جانشین» نیازی باشد.

یکدستی در یک تمرین

برخی واژه‌ها چند املای درست دارند (مثلاً «lower case» در برابر «lowercase»). هر جا در این سند سبکی یکدست توافق نشده باشد، این واژه‌ها باید در سراسر یک تمرین یکدست به کار روند.

استثناها

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

زبان

همه‌ی محتوا باید به انگلیسی آمریکایی نوشته شود، که در زمینه‌های گوناگون با انگلیسی بریتانیایی تفاوت دارد. در آینده ممکن است ترجمه‌های دیگری هم انجام شود، اما زبان «رسمی» Exercism انگلیسی آمریکایی است.

اندازه‌گیری‌ها

همه‌ی یکاهای اندازه‌گیری باید SI یا یکاهای برگرفته از SI باشند.

مخفف‌ها، سرنام‌ها و سرواژه‌ها

مخفف‌ها، سرنام‌ها و سرواژه‌ها اغلب از سایر گزینه‌های بیان دشوارترند و می‌توانند کسانی را که در حال یادگیری‌اند بیگانه کنند.

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

• خود مخفف از شکل مخفف‌نشده‌اش شناخته‌شده‌تر باشد
• متن بدون مخفف بیش از حد پرگو شود

هرگاه از مخفف استفاده می‌کنید، همیشه در نخستین کاربرد توضیح دهید که آن واژه چه معنایی دارد. این کار اغلب، اما نه همیشه، شامل بازکردن مخفف هم می‌شود. به‌ندرت پیش می‌آید که بازکردن صرف مخفف کافی باشد.

چند قاعده‌ی نمونه:

• «if I recall correctly» را به «IIRC» ترجیح دهید
• «as far as I know» را به «AFAIK» ترجیح دهید
• «queue» را به «FIFO» و «stack» را به «FILO» ترجیح دهید
• به‌جای توصیف یک رابط با «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») در توضیحات تمرین‌ها باید کم و اگر ممکن است اصلاً به کار نروند، اما در سایر متن‌های سایت (مثلاً متن‌های وب‌سایت و منتورینگ) محدودیتی ندارند.

بسیاری از راهنمایان سبک انگلیسی آمریکایی می‌گویند پس از مخفف‌های «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» را به کار ببرید.

کد

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