نوشتن توضیحات تحلیلگر

این سند اطلاعات و رهنمودهایی درباره‌ی نحوه‌ی نوشتن کامنت‌هایی که تحلیلگر تولید می‌کند ارائه می‌دهد.

فهرست مطالب

محتوای کامنت‌های تحلیلگر به‌صورت یک سند Markdown در مخزن exercism/website-copy ذخیره می‌شود. هر کامنت شامل یک رشته‌ی اشاره‌گر است، با قالب <track-slug>.<exercise-slug>.<comment-slug>، که به یک سند Markdown مشخص در مخزن website-copy پیوند می‌دهد.

برای مثال، ruby.two-fer.string-interpolation به آدرس https://github.com/exercism/website-copy/blob/main/analyzer-comments/ruby/two-fer/string_interpolation.md اشاره می‌کند.

نگارش

• از کامنت‌های بی‌دلیل پرحرف پرهیز کنید. مختصر بنویسید.
• بی‌طرفانه و مشاهده‌محور باشید؛ از جملات دارای بار عاطفی و کلی‌گویی بپرهیزید.
• توصیه را صریح بیان کنید.
• در صورت امکان، ابتدا توصیه را بیاورید و سپس توضیح را.
• از «me»، «I»، «we» و مانند آن پرهیز کنید، چون ربات یک انسان نیست.
• از «you» و «your code» پرهیز کنید، چون گاهی ممکن است حس قضاوت فرد را به‌جای کد منتقل کند.
• از کلماتی مثل «just»، «simply»، «obviously» پرهیز کنید، چون می‌توانند تحقیرآمیز به نظر برسند: اگر کامنت لازم است، پس آن نکته obviously چندان obvious نبوده است.
• از فرض‌کردن اینکه افراد چه می‌دانند و چه نمی‌دانند بپرهیزید. تنها استثنا، دانشی است که از تمرین‌های اصلی که پیش‌تر تکمیل شده‌اند می‌آید. از «as you know»، «as you remember»، «as you learned»، «now that we all understand x» بپرهیزید، چون حتی اگر چیزی گفته شده باشد، فرد لزوماً آن را درک نکرده است.

رهنمودها

• روانی را هدف بگیرید، نه تبحر: هدف یک مسیر زبانی در Exercism این است که به افراد راهی بدهد تا با سطح پایینی از تبحر، به سطح بالایی از روانی برسند. ما در این مسیر به دنبال روانی در نحوه‌ی نگارش، اصطلاحات و کتابخانه‌ی استاندارد زبان هستیم.
• در صورت امکان کد اصطلاحی پیشنهاد دهید؛ منظور از اصطلاحی کدی است که تقریباً همه‌ی توسعه‌دهندگانی که با آن زبان کد می‌نویسند (نه کسانی که فقط به‌عنوان سرگرمی می‌نویسند) آن را می‌نویسند. اگر پیشنهادی غیراصطلاحی می‌دهید، به این نکته اشاره کنید و توضیح دهید چرا آن پیشنهاد ممکن است همچنان مفید باشد.
• تفاوت را نام ببرید؛ تفاوت میان کاری که فرد انجام می‌دهد و آنچه در زبان «اصطلاحی» است.
• از اصطلاحات درست و نام‌گذاری مناسب استفاده کنید تا افراد بتوانند همان مفاهیم را جای دیگر تشخیص دهند و خودشان درباره‌شان تحقیق کنند.
• راه‌حل را ندهید. این توصیه‌ای کلی برای همه‌ی منتورینگ Exercism است. یادگیری زمانی ماندگار می‌شود که افراد خودشان پاسخ را کشف کنند. این تجربه‌ای بسیار هیجان‌انگیز است و همان ضربه‌ی احساسی آن را به‌یادماندنی می‌کند. اما اگر این کشف هیچ شور و هیجانی ایجاد نکند، کاملاً منطقی است که نشان دهید پاسخ چه شکلی است. برای مثال، ممکن است تصمیم بگیریم روی یک راه‌حل تأییدشده یک بهبود کوچک پیشنهاد دهیم؛ این کار بسیار کم‌هیجان‌تر از آن است که به کسی روی راه‌حلی که در حال رد شدن است یک نکته‌ی آموزشی بدهیم، و به همین دلیل ممکن است این مورد به‌جای یک پیوند، یک مثال را بطلبد.
• کامنت‌ها را بر اساس اهمیت مرتب کنید، به‌طوری که اولین کامنت مهم‌ترین و آخرین کامنت کم‌اهمیت‌ترین باشد.
• تعداد کامنت‌ها را قابل مدیریت نگه دارید. هدف، یک تا سه کامنت در هر تکرار است.
• یک کامنت را دو بار اضافه نکنید در یک تحلیل. افزودن همان کامنت با پارامترهای متفاوت، تکراری به حساب نمی‌آید.
• تنها در صورتی درباره‌ی قالب‌بندی کامنت بگذارید که قالب‌بندی یا لینت کردن بخشی جدایی‌ناپذیر از زبان باشد. در صورت امکان، دانش‌آموزان را به سمت ابزارهای قالب‌بندی خودکار راهنمایی کنید و/یا به هر راهنمای سبک رسمی پیوند بدهید.

چند تمرین نخست

برای چند تمرین نخست یک مسیر، موارد زیر بیش از پیش مهم‌اند:

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

مثال‌ها

در JavaScript، دانش‌آموزی یک ثابت سطح‌بالا با let نوشته است.

<!-- not following these guidelines -->

As you know, everyone uses const, you shouldn't use let or var.

این کامنت به دلایل زیر این راهنماها را رعایت نکرده است:

• عمل بعد از «توضیح» می‌آید.
• «As you know»: نمی‌دانیم آیا دانش‌آموز واقعاً می‌داند یا نه.
• «you shouldn't»: برای گفتن این جمله نیازی به «you» نیست.
• «everyone uses const»: این حرف درست نیست و می‌تواند باعث شود دانش‌آموز حس کند کار خیلی بدی کرده است.
• توضیح واقعی درباره‌ی چرایی این توصیه را ندارد.

<!-- better -->

Prefer `const` and `let` over `var`. The `const` declaration stops a variable
from being accidentally reassigned, which provides safety, and reduces
cognitive load for someone reading the code. [This article](https://medium.com/javascript-scene/javascript-es6-var-let-or-const-ba58b8dcde75)
explains the difference between the three.

در Go، دانش‌آموزی به‌جای استفاده از خطاهای داخلی، یک خطای سفارشی ساخته است:

<!-- not following these guidelines -->

I see you are creating a custom `error`. This is perfectly fine! If you did not
know about `errors.New` and `fmt.Errorf` have a look at them as they are much
simpler ways to create an error. Custom errors are helpful if you want to check
if an error is of a certain type later.

این کامنت به دلایل زیر این راهنماها را رعایت نکرده است:

• «I see»: تحلیلگر یک انسان نیست؛ از I پرهیز کنید.
• «This is perfectly fine!»: ظاهراً درست نیست، وگرنه این دلجویی لازم نبود. احتمالاً می‌توان این جمله را کاملاً حذف کرد؛ اگر می‌خواهید یک نکته‌ی کلی درباره‌ی وجود داشتن چیزی بدهید، می‌توانید دقیقاً همین را بگویید: «An alternative, equally valid way of doing x is y.»
• «If you did not know about»: این گروه واژگانی بیش از حد پرحرف را حذف کنید.

<!-- better -->

A custom `error` is typically used to provide custom behavior, or to distinguish
on type later. For simpler cases, it's more common to rely on `errors.New` or
`fmt.Errorf`. This [in-depth article](https://golangbot.com/custom-errors/) about
custom errors might be interesting.

CI

چون کامنت‌ها در همان مخزنی که تحلیلگر در آن قرار دارد نگهداری نمی‌شوند، هر تحلیلگر باید CI داشته باشد که بررسی کند آیا کامنت‌هایی که در آن تحلیلگر به‌خصوص استفاده می‌شوند (کامنت‌هایی که می‌توانند به خروجی تبدیل شوند) روی شاخه‌ی main در مخزن exercism/website-copy قرار دارند یا نه.

در زمان نوشتن این متن، این ایشو وضعیت هرگونه تعمیم این CI را، در صورت وجود، پیگیری می‌کند.