نوشتهی خوب
در این درس کلمههایی را یاد میگیری که با آنها دربارهی خودِ نوشته حرف میزنند. بازبینها با همین صفتها میگویند متن یا کد تو چه کم دارد: «more specific»، «more concise»، «not consistent».
صفت بعد از be و keep، و مقایسه با more
توصیههای نوشتن دو الگوی ساده دارند: «Be + صفت» (Be specific. Be concise.) و «Keep + چیز + صفت» (Keep it short. Keep the names consistent.). برای مقایسه، صفتهای کوتاه -er میگیرند (shorter، simpler) و صفتهای بلند more: more specific، more detailed، more accurate. در بازبینی زیاد میشنوی: «Could you be more specific?».
هشت کلمهی این درس
concise (کِنسایس): کوتاه و پرمعنی؛ بدون کلمهی اضافه
concise یعنی نوشتهای که همهی حرفش را با کمترین کلمهی ممکن میزند. با «کوتاه» فرق دارد: «update» کوتاه است ولی چیزی نمیگوید؛ «Fix crash on empty name» هم کوتاه است و هم کامل، پس concise است. برای رسیدن به آن، بعد از نوشتن یک بار برگرد و هر کلمهای را که بدون آن معنی عوض نمیشود خط بزن.
Keep your commit messages concise and clear.
پیامهای commit را کوتاه، پرمعنی و روشن نگه دار.
simple (سیمپِل): ساده
simple یعنی ساده: چیزی که تکههای کمی دارد و راحت فهمیده میشود. در نوشتن یعنی کلمهی آشنا بهجای کلمهی قلمبه (use بهجای utilize) و جملهی کوتاه بهجای جملهی تودرتو. در کد هم همین است: راه سادهای که همه میفهمند از راه زیرکانهای که فقط خودت میفهمی بهتر است.
Use simple words so that everyone can understand the docs.
از کلمههای ساده استفاده کن تا همه بتوانند مستندات را بفهمند.
short (شورت): کوتاه
short یعنی کوتاه، هم در اندازه و هم در زمان. در نوشتن فنی کوتاهی یک قانون است: جملهی کوتاه، پاراگراف کوتاه، خط اول commit زیر پنجاه حرف. خوانندهی تو معمولاً عجله دارد و فقط چند ثانیه نگاه میکند. در کد هم میبینیاش: short-circuit، shortcut و نوع دادهی short.
Keep the first line of the commit message short.
خط اول پیام commit را کوتاه نگه دار.
detailed (دیتِیلد): پرجزئیات، مفصل
detail یعنی «جزئیات» و detailed یعنی نوشتهای که جزئیات لازم را دارد. کوتاهنویسی همیشه خوب نیست: گزارش باگ باید detailed باشد، با نسخه، سیستمعامل، قدمها و متن خطا. قاعده این است: خط اول کوتاه، و جزئیات زیر آن برای کسی که لازمش دارد.
Thank you for the detailed bug report, it helped a lot.
ممنون از گزارش باگ مفصلت؛ خیلی کمک کرد.
specific (اِسپِسیفیک): مشخص، دقیق (نه کلی)
specific یعنی «مشخص»: دربارهی یک چیز معین، نه کلیگویی. «برنامه خراب است» کلی است؛ «دکمهی Save در صفحهی تنظیمات بعد از کلیک کاری نمیکند» specific است. هر چه مشخصتر بنویسی، جواب بهتری میگیری؛ چه از آدمها و چه از هوش مصنوعی. فعلش specify است: مشخص کردن.
Please be more specific: which page shows the error?
لطفاً دقیقتر بگو: کدام صفحه خطا را نشان میدهد؟
accurate (اَکیورِت): دقیق و مطابق با واقعیت
accurate یعنی چیزی که با واقعیت جور است و خطا ندارد. نوشتهی accurate همان چیزی را میگوید که واقعاً هست: کامنتی که با کد زیرش میخواند، مستنداتی که با نسخهی فعلی جور است. کامنتِ نادرست از نبودن کامنت بدتر است، چون خواننده را گمراه میکند. پس هر وقت کد را عوض کردی، کامنتش را هم بهروز کن.
This comment is no longer accurate, the function returns a list now.
این کامنت دیگر درست نیست؛ تابع حالا یک لیست برمیگرداند.
correct (کُرِکت): درست، صحیح
correct یعنی درست و بدون غلط. در نوشتن دو چیز را میگوید: یکی درستی حرف (اطلاعاتت غلط نباشد) و دیگری درستی زبان (املا و دستور). فعل هم هست و یعنی «درست کردن»: correct a typo. از همین کلمه autocorrect را داری که غلطهای تایپی را خودکار درست میکند.
Please check that the example in the README is correct.
لطفاً بررسی کن که مثالِ درون README درست باشد.
consistent (کِنسیستِنت): یکدست، هماهنگ با بقیه
consistent یعنی یکدست: همهجا به یک شکل. اگر یک جا نوشتی «log in»، جای دیگر ننویس «sign in»؛ اگر پیامهای commit با فعل امری شروع میشوند، همه همینطور باشند. نوشته و کدِ یکدست را راحتتر میشود خواند و جستوجو کرد. خیلی وقتها یکدست بودن از اینکه کدام سبک «بهتر» است مهمتر است.
Please keep the naming consistent with the rest of the file.
لطفاً اسمگذاری را با بقیهی فایل یکدست نگه دار.
نکتههای نوشتن مستندات
Writing tips for our docs
1. Be concise. Cut every word that adds nothing.
2. Use simple words and short sentences. Write "use", not "utilize".
3. Be specific. "The Save button does nothing" is better than "It is broken".
4. Be accurate. Test every example before you publish it.
5. Be consistent. Pick one word for one thing and keep it.
A detailed guide is fine, but start with a short summary. And check that your spelling is correct.
نکتههای نوشتن برای مستندات ما
۱. کوتاه و پرمعنی بنویس. هر کلمهای را که چیزی اضافه نمیکند حذف کن.
۲. از کلمههای ساده و جملههای کوتاه استفاده کن. بنویس «use»، نه «utilize».
۳. مشخص بنویس. «دکمهی Save هیچ کاری نمیکند» بهتر است از «خراب است».
۴. دقیق باش. هر مثال را قبل از انتشار امتحان کن.
۵. یکدست بنویس. برای هر چیز یک کلمه انتخاب کن و همان را نگه دار.
راهنمای مفصل اشکالی ندارد، ولی با یک خلاصهی کوتاه شروع کن. و نگاه کن که املایت درست باشد.