چند بار شده که موقع نوشتن یه کامنت حس خوبی داشته باشید که دارید کدی رو توضیح می‌دید و برای آیندگان! اون توضیحات رو به جا میزارید؟ اصلا کد هاتون رو کامنت می‌کنید یا نه؟
توی این بخش از سری مقاله های برداشت های من از کتاب Clean Code میخوایم ببینیم که چه موقع باید از کامنت استفاده کنیم؟ اگه کد بیسی پر از کامنت باشه آیا کد بهتر و تمیز تریه؟ برای این که بهتر هدف این کتاب رو درک کنین خیلی خوبه که بیشتر از تجربه های کد نویسی به تجربه های خوندن و تغییر دادن کد هایی که خودتون ننوشتید برگردید. چند بار شده که از خوندن یه کد و نفهمیدنش دیوونه شدین؟ چند بار بوده که کامنت های یه کد رو خوندید و اون کامنت ها بهتون دروغ گفتن؟ یا تا حالا شده که موقع خوندن یه کد به خاطر بیش از حد بودن کامنت ها و این که مجبورید کلی اسکرول کنید تا یه تابع ساده رو بخونید کلافه شید؟ این بخش راجع به اینه که کدی بنویسیم که برای بقیه این دردسر ها رو درست نکنه، یا حداقل کمتر درست بکنه!
واقعیت اینه که وقتی نیاز به نوشتن کامنت رو حس می‌کنیم تا توضیح بدیم یه کد چه کاری رو داره انجام میده باید سریعا حساس شیم که چرا کدی نوشتیم که خودش خودش رو توضیح نمی‌ده؟
بیشتر چیزایی که تا اینجا در مورد کد تمیز گفتیم برای این بود که کد ها خودشون توضیح دهنده خودشون باشن و با اسم های خوب و ساختار های تمیز و خلاصه، هر برنامه نویس دیگه ای که اون ها رو می‌خونه به راحتی متوجه بشه که چه کاری داره انجام می‌شه.
پس دفعه بعدی که خواستید با افتخار شروع به نوشتن کامنت کنید برای کدتون اول ببینید که چرا اون کد به اندازه کافی واضح نیست و نیاز به کامنت داره. اگر تونستید کد رو طوری تغییر بدید که نیازی به کامنت نباشه اون وقت به خودتون افتخار کنید و اگه در نهایت مجبور شدید که کامنت رو بنویسید به اون کد به چشم یه شکست نگاه کنید!
تغییر دادن کد برای قابل فهم شدن خیلی از وقتا فقط به معنی اسم گذاری درست و نوشتن تابع های واضحه، به همین راحتی.
چرا کامنت خوب نیست؟ اول این که این در مورد هر کامنتی نیست و بیشتر در مورد کامنت هاییه که راجع به عملکرد یه کد توضیح میدن و این نوع کامنت‌ها هستن که بیشتر مشکل در مورد اون هاست. به طور خلاصه به این دلایل برای رد کامنت های توضیح دهنده کد می‌شه اشاره کرد:
کامنت های دروغ گو
نکته ای که در مورد کامنت وجود داره اینه که مستقیما به اجرای کد ارتباط ندارن و به همین خاطر به موقع آپدیت نمیشن و بعد از مدتی احتمالا شامل تغییرات کد نمیشن و تبدیل به جمله های گمراه کننده برای کسی که کد رو می‌خونه میشن.
* اگر در مورد متودولوژی Extreme Programming مطالعه کنین، می‌بینید که یکی از توصیه‌های اکید اینه که کد رو توسط چیزی که روی اجرای کد تاثیر نداره داکیومنت نکنید (حتی گراف ها و مدل های UML)
درسته که می‌شه گفت برنامه نویس خوب کامنت و مدل و داکیومنت ها رو همراه کد آپدیت می‌کنه، اما واقعیت اینه که خیلی مواقع این اتفاق نمی‌افته و بهتره که برنامه نویس خوب از اول کدش رو طوری بنویسه که نیازی به کامنت نداشته باشه.
باقی موندن کد های بد
یکی دیگه از جاهایی که کامنت ها نقش منفی دارند اینه که بهانه ای به ما میدن که کد های کثیف رو نگه داریم و به جای اصلاح شون با چندتا کامنت ازش فرار کنیم.
همونطور که گفته شد، همه ی کامنت‌ها هم بد نیستن. چه کامنت هایی توی دسته خوب قرار می‌گیرن؟
کامنت های قانونی
چیزهایی مثل اطلاعات در مورد license های قانونی، copyright و ... داخل کد ها برای همیشه می‌تونن زندگی کنن و کاربرد داشته باشند.
توضیح ایده و هدف
بعضی وقت ها کامنت ها نه عملکرد مستقیم کد ، بلکه ایده پشت یه روش رو توضیح میدن و هرچند مشکل آپدیت نبودن اینجا هم می‌تونه اتفاق بیافته اما احتمالش کمتره و به طور خلاصه اینطور کامنت ها اگر واقعا جایی که ایده خاصی به کار رفته نوشته بشن، نسبت سود به ضرر شون نسبت مناسبیه.
هشدار ها
گاهی اوقات کامنت ها نقش هشدار و اعلام خطر در مورد بخشی از کد هستند که خوبه که برنامه نویس های بعدی در مورد اون ها بدونن. فرض کنید داخل یک کد بیس یک تست غیر فعال شده باشه، اینجا خوبه که کنار اون تست نوشته بشه که به چه دلیل غیرفعال شده تا افراد بعدی یا حتی خودمون بعد مدتی که بهش برمیگردیم بدونیم که چه اتفاقی افتاده بوده.
کامنت های TODO
ممکنه به کدی برخورد کنین که ببینید مشکلی داره یا نیاز به refactor و اصلاح داره، ولی به دلایلی وقت یا امکان این که اون کد رو ادیت کنید تو همون زمان ندارید. این جا می‌شه از کامنت های TODO استفاده کرد که در واقع شما با این روش مینویسید که چه کاری باید انجام شه تا بعدا بهش برگردید و تغییر رو انجام بدید.
کامنت های داکیومنت API
وقتی سرویسی برای استفاده عمومی تولید می‌کنید، ابزار هایی مثل javadoc,phpdoc و ... وجود دارن که به شما این امکان رو میدن که برای تولید داکیومنت مربوط به اون API ها، از کامنت گذاری روی توابع استفاده کنین و بعد با اجرا کردن یک اسکریپت روی کد، فایل های داکیومنت به طور خودکار تولید می‌شه و می‌شه در اختیار استفاده کننده های اون سرویس قرارش داد. تنها نکته منفی در مورد اون کار همون مورد دروغ گو شدن کامنت می‌شه که باید با دقت در موردش عمل کرد و حتما با هر تغییر سرویس کامنت مربوط به داکیومنت اون هم آپدیت بشه.
در مورد این‌که چرا کامنت ها خیلی از وقت‌ها در واقع ایده خوبی نیستند به اندازه کافی توضیح داده شد و الان فقط میخوام مصداق های کامنت بد رو مرور کنم:
به درد نخور ها
منظور از کامنت های به درد نخور، هر کامنتیه که در واقع اطلاعات جدید و اضافه ای بهمون نمی‌ده. مثلا کاری که کد داره به وضوح انجام میده رو توضیح بده و ... .
کامنت های غیر دقیق
بعضی کامنت ها با این‌که فکر خوبی پشت شون هست ، اما برنامه نویس موقع نوشتن شون به اندازه کافی دقیق نیست و باعث گمراهی کسی می‌شه که بعدا اون کد رو می‌خونه.
کامنت های اجباری
معمولا با فکر کمک به بهتر داکیومنت شدن کد، توی بعضی تیم های برنامه نویسی، قانونی اعلام می‌شه که تمام توابع داخل کد باید ساختار خاصی از کامنت رو داشته باشن که در مورد خوشون،. ورودی ها و خروجی شون توضیح بده. این کار هرچند با نیت خوبی (داکیومنت کردن) انجام می‌شه، اما در حقیقت و توی بلند مدت باعث ایجاد حجم زیادی کامنت غیر دقیق، غلط و بروز نشده می‌شه. به جای قانون های ظاهری برای کامنت گذاری باید سراغ ایجاد طرز فکر درست نسبت به داکیومنت کردن و البته محدود کردن داکیومنت به جاهایی که واقعا نیازش وجود داره برید.
یادگاری ها
منظور از یادگاری ها هر چیزیه که ارتباط مستقیمی با خود کد نداره. کد جای یادگاری نوشتن نیست. این که ارتباط بین کد و تسک مربوط بهش رو توی کد نگه دارید، یا با هر تغییر بالای کد توضیح اضافه کنید که توی چه تاریخی چه تغییری انجام دادید و کارهایی مشابه این. برای این ها از سیستم ورژن کنترل استفاده کنید. تاریخچه تغییرات و حتی ارتباط با تسک های مربوطه ش رو توی git history یا هر ورژن کنترل دیگه ای می‌شه نگه داشت و نباید داخل کد نگهداری بشه.
کد های قدیمی
اگر کدی رو دیگه لازم ندارید پاکش کنید. نگه داشتن کد قدیمی به شکل کامنت باعث بزرگ شدن و ترسناک تر شدن کد می‌شه. وقتی شما کدی رو به صورت کامنت نگه می‌دارید، برنامه نویس های بعدی هم جرعت پاک کردنش رو نخواهند داشت.
این خلاصه ای از محتوای کتاب Clean Code بود در مورد کامنت گذاری داخل کد. مشابه همه مقاله های سری برداشت های من از این کتاب شما رو توصیه می‌کنم به خواندن خود کتاب، اون هم نه به شکل یک مرتبه بلکه به نحوی که محتواش همیشه خاطرتون بمونه.
اگر این مطلب براتون جالب بوده بقیه مقاله های این سری رو هم مطالعه کنید و همینطور با بقیه به اشتراک بگذارینشون.
