کد تمیز یک هنر است مانند طراحی یک نقاشی یا نواختن یک موسیقی.
کدهای کثیف در زمان کوتاه شما را به نتیجه میرساند ولی در زمان ورود نرمفزار شما به بازار و استفاده کاربران از نرمفزار شما شما با حجم عظیمی از باگ ها تسک ها و بروزرسانی ها رو به رو خواهید شد و در آن بازه زمانی است که پیچیدگی ها + وابستگی ها در کد شما برابر میشود با ورشکستگی بیزینس یک مجموعه.
بصورتی کلی کامنت نویسی هرچقدر کم باشد بهتر است. شخصی که برای هر تابع هر کلاس و .. کامنت نویسی میکند خودش بهتر از هر کسی میداند که به چه مقدار کد هایش گنگ است و در ارسال مطالب ناتوان است و خودش هم در مرور زمان متوجه این میزان از گیچی و چرخش های مکرر در کد خود میشود.
حتی کامنت نویسی هم قوانین خود را دارد شما نمیتوانید به خودی خود و بدون هیچ گونه استانداردی شروع به نوشتن کامنت های خود در کد منبع کنید.
Legal Comments
گاهی اوقات استانداردهای کدنویسی شرکتی ما را مجبور می کند comment های خاصی را برای حقوق هایی بنویسیم
به عنوان مثال، اظهارات copyright و authorship معقول است
از جمله چیزهایی که در ابتدای هر فایل منبع باید در یک comment قرار دهید.
Clarification
گاهی اوقات ترجمه معنای برخی استدلال های مبهم فقط مفید است
به طور کلی بهتر است راهی برای این استدلال پیدا کنید
مقدار یا مقدار بازگشتی به خودی خود واضح است. اما زمانی که بخشی از کتابخانه استاندارد است، یا در
کدی که نمی توانید آن را تغییر دهید، سپس یک نظر شفاف کننده مفید می تواند مفید باشد.
TODO Comments
در برخی از زمان ها ما کلاس یا یک تابع ناقص داریم یا می خواهیم بخشی از یک کد را گسترش دهیم در اینجا میتوانیم برای یادآوری از Todo comments ها استفاده کنیم و خوبی این نوع کامنت ها track کردن آنها از طریق خود IDE است.
بطور کلی کامنت خوب کامنتی است که آن را ننویسید.
Mumbling
کامنت گذاشتن فقط به این دلیل که فکر می‌کنید باید این کار را انجام دهید یا به این دلیل که فرآیند آن را ایجاب میکند، فقط یک از صورت مسعله فرار کردن است. لطفا قبل از نوشتن هر گونه کامنتی به آن کامنت فکر کنید.
Journal Comments
گاهی اوقات افراد هر بار که یک ماژول را ویرایش می کنند، یک comment به ابتدای ماژول اضافه می کنند.
این comment ها به‌عنوان نوعی مجله یا گزارش از هر تغییری که تاکنون رخ داده است جمع میشوند
و ساخته میشوند
Position Markers
گاهی اوقات برنامه نویسان دوست دارند موقعیت خاصی را در یک فایل منبع علامت گذاری کنند
برای مثال
//--------------------- api fetch ----------------
https://github.com/torvalds/linux
نوشتن و ساختن یک برنامه مانند نواختن یک موسیقی است یک نوازنده میتواند یک ساز ناکوک را در مقابل حضاران گونه ای بنوازد که کسی متوجه کیفیت پایین نت های نواخته شده نشود اما یک موزیسین و یک نوازنده کار بلد به سادگی میتواند متوجه کیفیت پایین آن اجرا شود.
بصورت کلی اگر شما در یک تیم بزرگ هستید که همگی یک استاندارد کامنت گذاری دارید و چند دولوپر برای انجام اپدیت های مکرر بر روی کامنت های پروژه خود دارید میتوانید از کامنت گزاری های استاندارد استفاده کنید ولی باید این رو درنظر بگیرید که اگر در یک تیم کوچک یا متوسط هستید کامت گذاری در پروژه میتواند از تبعات سنگینی برخوردار شود شما باید این رو در نظر بگیرید که شما باید تسک هایی از قبیل باگ ها آپدیت ها ریفکتور ها اضافه کردن فیچر های جدید و ... را انجام دهید و اگر تمامی این ها شامل کامنت گذاری باشد شما کاملا تمامی بهره وری سیستم محصول رو نابود کردید و در آینده آن مجموعه محکوم به شکست میشود.
با احترام الیوت
منبع : Clean Code A Handbook of Agile Software Craftsmanship by Robert C.Martin (Uncle Bob)
