جوگیرساختن مخاطب برای خواندن تا ته

بعد از خوندن این فصل، خواهید دونست که آیا کامنت اونقدرا هم که رسانه های معاند میگن خوب هست یا نه؟ کامنت خوب چیه کامنت بد چیه ؟ ویژگی های هر دسته چیه ؟ وقتی میشه با کد نطق کرد چرا کامنت گذاشت؟ خلاصه این فصل خیلی خوبه و شاید توش کد موفقیت در زندگی هم پیدا شد :‌)

فصل چهارم – comments

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

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

Code never lies, comments sometimes do

Comments Do Not Make Up for Bad Code

بچه زرنگ اگر فکر میکنی با کامنت میتونی اون کدای آشغالی که زدیو جبران کنی سخت در اشتباهی. کامنت مثل عطر عمل میکنه. قراره بی بویی رو به خوش بویی تبدیل کنه. اگه بوی بد میدی باید بری حموم و بشوری. با کامنت نمیشه کد بد رو شست.

Explain Yourself in Code

به جای اینکه توی کامنت توضیح بدی که کد داره چیکار میکنه، بیا کدت رو خوب تر کن که دیگه نیازی به توضیح نباشه.

خب ازینجا به بعد کامنت یه جاهایی توی خوب هاست یه جاهایی توی بدها. بریم ببینیم کجا خوبه کجا نامهربونه.

Good Comments-Legal Comments

از جاهایی که کامنت به خوبی نقش ایفا میکنه اونجاهایی که مثلا میخوایم یه چیزی راجع به کپی‌رایت بگیم یا هنرمند کد رو ذکر کنیم.

Good Comments-Informative Comments

از جمله مکان هایی که واقعا نمیتونیم با کد توضیح بدیم ومجبوریم کامنت بذاریم، اونجاییه که برای دادن اطلاعات کامنت میذاریم یا سهولت بدست آوردن اطلاعات راجع به کد. مثلا یه کدی نوشتیم که یه regex خاصی رو داره هندل میکنه. اگر بیایم یه مثال از اون regex بالاش بنویسیم جامون تو خلد برینه.

Good Comments-Explanation of Intent

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

Good Comments-Warning of concequences

 برای اینکه یکسری عواقب رو برای برنامه نویس بعدی ( که ممکنه خودمون هم باشیم ) مشخص کنیم. مثلا کامنت بذاریم که : اگر تابع ممد رو خواستی عوض کنی عواقبش با خودته‌:) 

دقیقا مناسب وقتایی که کدها با تف به هم چسبیدن. لازمه بگیم اگر یه چیزو تکون بده ده چیز دیگه هم به لرزه درمیان.

Good Comments-TODO Comments

وقتایی که میخوایم یه کارو به تعویق بیندازیم به هردلیلی، میخوایم که یه متذکر داشته باشیم که بعدا یادمون نره. مثلا فلان ویژگی به این تابع اضافه بشه یا فلان باگ رو حواست باشه بعدا هندل کنی. این مواقع هم کامنت گذاری از کارای بچه های خوبه . البته نباید این بهانه ای باشه تا اینکه کد کثیف رو با یه تودو رها کنی.

حالا که خودمونیم، ته پروژه همیشه یادمون میره تودو هارو دو کنیم : )

میریم سراغ کامنت های بد …

Bad Comments-Redundant Comments

اینجا میریم سراغ حرف لینوس تروالدز که میگفت

talk is cheap show me the code

وقتی که کد گویای همه چیز هست دیگه نیازی به کامنت گذاری نیست. وقتی واضحه که توی تابع ممد، ورودی ها باهم جمع میشن و در خروجی نتیجه رو چاپ میکنه چرا میای باز بالاش توضیح میدی اینا رو ؟ خوش‌خدمتی؟

Bad Comments-Mandated Comments

خیلی احمقانس که بگیم هر فیلدی یا هر تابعی باید کامنت داشته باشه. جاواداک نیستیم که.

 

Bad Comments-Journal Comments

بعضیاتون هم دیده شده که وقتی جایی رو از کد تغییر میدید بالای اون جا مینویسید که : تغییر داده شد و تاریخ هم میزنید.

مگه تخت جمشیده که یادگاری مینویسید رو کد؟

Bad Comments-Noise Comments

کامنتی که هیچ اطلاعاتی به آدمی اضافه نکنه مثل زنبور بی عسله. اسم تابع واضح نوشته شده که ممد. بعد بالاش چرا کامنت میذاری که این تابع ممد است؟ ممد خودش زبون نداره مگه؟

 

Bad Comments-Don’t Use a Comment When You Can Use a Function or a Variable

گره ای که با دست تغییر اسم متغیر حل میشه رو چرا با دندون اضافه کردن کامنت میخای باز کنی؟

 

Bad Comments-Position Markers

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

کامنت بد :

// Actions //////////////////////////////////

Bad Comments-Closing Brace Comments

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

 

Bad Comments-Attributions and Bylines

/* Added by MrBug */

جهت خود ستایی و ریا میای بالای کد مینویسن که آره اینو من نوشتم. چیزایی مثل گیت معلوم میکنه چیو کی نوشته . به خودت زحمت نده، جهان پهلوان

Bad Comments-Commented-Out Code

بارها شده که میرسیم ته پروژه و میبینیم کلی کد کامنت شده داریم و مثل مامانا به خودمون میگیم که حالا شاید به درد خورد، بذاریم بمونه. اون کد ها رفاقت نیست که هرچی بیشتر بمونه ارزشش بیشتر بشه که. پاکش کنید نهایتش اگر نیاز پیدا کردید توی ورژن کنترل تون هست دیگه .(گیت)

Bad Comments-Nonlocal Information

راجع به همون چیزهای دور و بر کد کامنت بذار. نمیخواد روی در بنویسی که دیوار هم بشنوه. مثلا بیای بالای تابع اندازه قد ممد، بگی که ممد چه مهربونه قدر منو میدونه.

Bad Comments-Too Much Information

باز میای برای خوش‌خدمتی کردن، به عنوان مثال برای تابع ممد، کل تاریخ رو توی کامنت بررسی میکنی که چه کسایی اسمشون ممد بوده. ممد تا الان چکار ها کرده. ممد چقد مهربونه و ….
توضیحات اضافه برای نخوندنه. پس ننویسش.