بتل کد Battle Codeدارد باز می‌شود…

کامنت

کد را یک بار می‌نویسی و ده بار می‌خوانی. این هشت کلمه برای توضیح‌هایی است که کنار کد می‌گذاری: کامنت، علامت‌های TODO و FIXME، و متن راهنمای تابع‌ها.

کامنت با زمان حال ساده، TODO با فعل امری

کامنت چیزی را می‌گوید که همیشه درست است، پس با زمان حال ساده می‌نویسندش: «This function returns the total» (فاعل it است و فعل s می‌گیرد). ولی TODO و FIXME دستور کار هستند و با فعل امری، یعنی شکل ساده‌ی فعل بدون فاعل، شروع می‌شوند: «TODO: Add a test». جمله را با حرف بزرگ شروع کن و کوتاه نگهش دار.

هشت کلمه‌ی این درس

code comment (کُد کامِنت): توضیحی که برای آدم‌ها کنار کد می‌نویسی

comment در انگلیسی یعنی «نظر» یا «توضیح». code comment خطی است که کامپیوتر آن را نادیده می‌گیرد و فقط برای آدمی نوشته شده که بعداً کد را می‌خواند (که خیلی وقت‌ها خود تو هستی). کامنت خوب نمی‌گوید کد «چه کار» می‌کند، چون آن را خود کد می‌گوید؛ می‌گوید «چرا» این‌طور نوشته شده. کامنت را کوتاه، با زمان حال ساده و با حرف بزرگ در اول جمله بنویس.

Add a short code comment to explain why we skip the first row.

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

TODO (تو دو): کاری که هنوز باید انجام شود

to do در انگلیسی یعنی «برای انجام دادن»، و to-do list همان فهرست کارهاست. برنامه‌نویس‌ها در کامنت با حروف بزرگ می‌نویسند TODO تا بگویند «این‌جا هنوز کاری مانده». ادیتورها این کلمه را رنگی نشان می‌دهند و می‌توانی همه‌ی TODOهای پروژه را یک‌جا جست‌وجو کنی. بعد از TODO یک دونقطه بگذار و کار را با یک فعل امری بنویس.

I left a TODO in the code for the missing error message.

برای پیام خطایی که هنوز نیست، یک TODO در کد گذاشتم.

FIXME (فیکس می): نشانه‌ی کدی که خراب است و باید درست شود

fix me یعنی «مرا درست کن»: انگار خود کد دارد از تو کمک می‌خواهد. برنامه‌نویس وقتی می‌داند یک تکه کد اشکال دارد ولی الان وقت درست کردنش را ندارد، بالای آن یک کامنت با FIXME می‌گذارد. خوب است بنویسی دقیقاً چه چیزی خراب است و در چه حالتی، تا نفر بعدی از صفر شروع نکند.

There is a FIXME above this function, so be careful with it.

بالای این تابع یک FIXME هست، پس با احتیاط از آن استفاده کن.

docstring (داک‌اِسترینگ): متن راهنمای یک تابع، درون خود کد

docstring از دو تکه ساخته شده: doc (کوتاه‌شده‌ی documentation، یعنی مستندات) و string (رشته). در پایتون، رشته‌ای است که درست زیر خط def می‌نویسی و می‌گوید این تابع چه می‌گیرد و چه برمی‌گرداند. فرقش با کامنت این است که پایتون آن را نگه می‌دارد و با help()‎ نشانش می‌دهد. جمله‌ی اولش کوتاه است و با فعل شروع می‌شود: Return…، Calculate…

Every public function should have a docstring with a short example.

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

description (دیسکریپشِن): توضیح، شرح

description اسمِ فعل describe (توصیف کردن) است و یعنی متنی که می‌گوید یک چیز چیست یا چه کار می‌کند. در برنامه‌نویسی همه‌جا یک جای خالی به این اسم هست: توضیح مخزن در گیت‌هاب، توضیح یک pull request، توضیح یک پکیج. آن‌جا در چند جمله می‌نویسی چه چیزی را عوض کرده‌ای و چرا.

Please write a clear description for your pull request.

لطفاً برای pull request خودت یک توضیح روشن بنویس.

summary (سامِری): خلاصه

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

Start the report with a one-line summary of the problem.

گزارش را با یک خلاصه‌ی یک‌خطی از مشکل شروع کن.

explanation (اِکسپلِنِیشِن): توضیحِ دلیل یا روش کار

explanation اسمِ فعل explain (توضیح دادن) است. فرقش با description این است که description می‌گوید چیزی «چه هست»، ولی explanation می‌گوید «چرا» یا «چطور». وقتی کد عجیبی می‌نویسی (مثلاً یک عدد خاص یا یک راه دور زدن)، یک explanation کوتاه در کامنت بگذار تا کسی آن را اشتباهی پاک نکند.

Thanks for the explanation, now I understand why the test failed.

ممنون از توضیحت، حالا می‌فهمم چرا تست رد شد.

readable (ریدِبِل): خوانا، راحت برای خواندن

read یعنی خواندن و پسوند ‎-able‎ یعنی «شدنی»؛ پس readable یعنی چیزی که راحت خوانده می‌شود. کد readable کدی است که اسم‌هایش معنی دارند، خط‌هایش کوتاه‌اند و بدون کامنت زیاد هم فهمیده می‌شود. در بازبینی کد زیاد می‌شنوی: «این را readable‌تر کن». اسمش readability است.

Good names make the code more readable than long comments do.

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

راهنمای کامنت‌نویسی یک تیم

How we write comments

A code comment explains why, not what. Keep it short and readable.

Every function has a docstring. Its first line is a one-line summary. A longer description can follow.

Use TODO for work that is not done, and FIXME for code that is broken. Always add a short explanation:

# TODO: Add a test for empty names.
# FIXME: This fails on leap years.

ما چطور کامنت می‌نویسیم

کامنت کد توضیح می‌دهد «چرا»، نه «چه». آن را کوتاه و خوانا نگه دار.

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

برای کاری که انجام نشده TODO بگذار و برای کدی که خراب است FIXME. همیشه یک توضیح کوتاه هم اضافه کن:

# TODO: برای اسم‌های خالی یک تست اضافه کن.
# FIXME: این در سال‌های کبیسه خطا می‌دهد.