یکی از بحث‌برانگیزترین موضوعات در کدنویسی تمیز، استفاده از کامنت‌هاست. بسیاری از برنامه‌نویسان تصور می‌کنند هرچه کامنت بیشتری در کد باشد، کیفیت آن بالاتر است. اما در فلسفه‌ی Clean Code واقعیت کمی متفاوت است.

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

بخش اول: کد خوب باید خودش صحبت کند

هدف اصلی در کدنویسی تمیز این است که کد تا حد ممکن واضح و قابل فهم باشد. اگر برای توضیح یک خط کد مجبور به نوشتن کامنت هستید، احتمالاً نام متغیر یا ساختار آن به اندازه کافی واضح نیست.

// کامنت غیرضروری

// افزایش سن کاربر

user.Age = user.Age + 1;

// نسخه تمیزتر

user.IncreaseAge();

در مثال بالا، تابع IncreaseAge به‌تنهایی هدف عملیات را مشخص می‌کند و دیگر نیازی به توضیح اضافی وجود ندارد.

بخش دوم: چه زمانی کامنت ضروری است؟

با وجود تأکید بر خوانایی کد، در برخی شرایط کامنت‌ها بسیار مفید و حتی ضروری هستند.

موارد مناسب برای استفاده از کامنت:

• توضیح منطق پیچیده یا الگوریتم‌های غیرمعمول
• هشدار درباره پیامدهای یک عملیات حساس
• ثبت تصمیمات معماری یا محدودیت‌های سیستم
• یادداشت‌های موقت برای توسعه آینده (TODO)

// TODO: بهینه‌سازی این کوئری برای حجم داده‌های بالا

var users = await _context.Users

.Where(u => u.IsActive)

.ToListAsync();

کامنت‌های TODO کمک می‌کنند نقاطی از سیستم که نیاز به بهبود دارند در طول توسعه فراموش نشوند.

بخش سوم: کامنت‌های خطرناک

یکی از بزرگ‌ترین مشکلات کامنت‌ها این است که با گذشت زمان ممکن است با کد همگام نباشند. وقتی توسعه‌دهنده کد را تغییر می‌دهد اما کامنت را به‌روزرسانی نمی‌کند، آن کامنت به یک منبع اطلاعات اشتباه تبدیل می‌شود.

// دریافت لیست کاربران فعال

var users = _context.Users.ToList();

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

بخش چهارم: مستندسازی API

در پروژه‌هایی که API عمومی ارائه می‌دهند، استفاده از مستندسازی ساختاریافته اهمیت زیادی دارد. در اکوسیستم .NET معمولاً از XML Documentation برای توضیح متدها و پارامترها استفاده می‌شود.

/// دریافت اطلاعات کاربر بر اساس شناسه

/// 

///شناسه کاربر

/// اطلاعات کامل کاربر

public async Task GetUserAsync(int id)

{

return await _context.Users.FindAsync(id);

}

این نوع مستندسازی به ابزارهایی مانند Swagger یا IntelliSense کمک می‌کند تا توضیحات دقیق‌تری به توسعه‌دهندگان ارائه دهند.

نتیجه‌گیری بخش دوم

کامنت‌ها باید آخرین راه‌حل باشند، نه اولین انتخاب. اگر کد شما با نام‌گذاری مناسب و ساختار درست نوشته شده باشد، در بسیاری از موارد نیازی به توضیح اضافه نخواهد داشت.

در نهایت، بهترین کامنت همان کدی است که بدون توضیح قابل فهم باشد.

در مقاله بعدی به سراغ یکی از مهم‌ترین اصول طراحی نرم‌افزار یعنی اصل مسئولیت واحد (SRP) و نقش آن در طراحی کلاس‌های تمیز خواهیم رفت.