کتاب Clean Code
فصل 4 : کامنت ها
کدی که بد هست را کامنت نکن بلکه بازنویسیش کن.
هیچ چیز نمی‌تواند مانند یک کامنت خوب مفید باشد. هیچ چیز به اندازه کامنت های ناخوشایند نمی‌تواند یک ماژول را دچار بهم ریختگی کند. هیچ چیز نمی‌تواند به اندازه یک کامنت قدیمی بیهوده‌ای که اطلاعات غلط می دهد، خطرناک باشد.
کامنت ها مانند فهرست شیندلر ( اشاره به فیلم معروف Schindler ) نیستند. آنها ” مطلقا خوب” نیستند. در واقع کامنت در بهترین حالت عمل ناخوشایندی است که باید انجام شود. اگر زبان برنامه نویسی ما به اندازه کافی گویا می‌بود و یا اگر ما استعداد این را داشتیم که با استفاده از این زبان مقصود خودمان را به خوبی بیان کنیم، شاید نیازی به نوشتن کامنت های بسیاری نبود و شاید اصلا نیازی نبود.
استفاده مناسب از کامنت ها باعث عدم شکست ما در کد می‌شود. توجه داشته باشید که من از کلمه شکست استفاده کردم. منظور من از گفتن آن این است که کامنت ها همیشه شکست به حساب می‌آیند. ما باید کامنت ها را داشته باشیم زیرا همیشه نمی‌توانیم آنچه را که دقیقا منظور ما است بدون کامنت نمایش دهیم اما استفاده از آنها نیز دلیلی بر جشن گرفتن نیست.
بنابراین هنگامی که در موقعیتی قرار می‌گیرید که نیاز به نوشتن کامنت دارید، فکر کنید و سپس ببینید که آیا راهی برای تبدیل جداول و گویا کردن کدتان وجود دارد یا خیر. هر زمانی که کد خودتان را به درستی نشان دادید باید خودتان را تشویق کنید. هر بار که شما کامنتی می‌نویسید باید در توانایی بیان خود احساس شکست کنید.
چرا من کامنت ها را دست پایین می‌گیرم؟ زیرا آنها دروغ می گویند. ولی نه همیشه و عمدا، اما اغلب اوقات کامنت ها دروغ می گویند. قدیمی ترها در مورد کامنت میگویند، کامنت ها ناتوان‌تر از این هستند که بتوانند کد را شرح دهند و به احتمال زیاد فقط یک اشتباه هستند. دلیل آن ساده است زیرا برنامه نویسان به طرز واقع بینانه ای قادر به نگهداری آنها نیستند.
کد تغییر می‌کند و تکامل می یابد. تکه های کد از اینجا به آنجا حرکت می‌کنند. این تکه ها شکافته‌شده و باز تولید می‌شوند و سپس باهم ترکیب شده تا آنچه در ذهن ما است را شکل دهند. متاسفانه کامنت‌ها همیشه از این موارد پیروی نمی‌کنند یا بهتر بگوییم آنها را نمیتوان دنبال کرد. اغلب کامنت ها از کدی که در حال توصیفش هستند جدا شده و دچار فرسودگی می‌شوند. به عنوان مثال به این کامنت و خطی که برای آن در نظر گرفته شده است نگاهی بیندازید:
متغیرهای نمونه ای دیگری که در کد بالا هستند،احتمالا بعدا بین کامنت و ثابت HTTP_DATE_REGEXP قرار گرفته اند.
چنین برداشتی هم امکان پذیر است که برنامه نویسان کد بالا، باید به اندازه کافی منظم باشند و کامنت های خود را در بالاترین حالت از تعمیر، ارتباط و دقت نگهداری کنند. من موافقم، باید باشد. من ترجیح می‌دهم که انرژی در جهت تولید کد بسیار شفاف و گویا صرف شود که در همان ابتدای کار نیازی به کامنت ها نداشته باشد. کامنت های نادرست، همیشه بدتر از نبود کامنت هستند. کامنت های نادرست، فریبنده و گمراه کننده هستند. آنها انتظاراتی را فراهم می‌کنند که هیچ گاه برآورده نخواهد شد. کامنت ها قوانین قدیمی که نیازی به آنها نیست و نباید ادامه پیدا کنند را تنظیم می‌کنند.
این حقیقت تنها در یک مکان نمایان می‌شود و آن کد می‌باشد. این کد است که واقعا به شما می‌گوید که چه کاری انجام می‌دهد. کد تنها منبع دقیق برای اطلاعات است. بنابراین گاهی اوقات کامنت ها در کد نیاز است اما تا جایی که امکان دارد باید انرژی صرف کنیم که آنها را به حداقل برسانیم.
کامنت ها کد بد را درست نمی کند
کد بد یکی از دلایل رایج در نوشتن کامنت ها می‌باشد. ما ماژولی را می‌نویسیم و می‌دانیم که گیج کننده و ناسازگار است. ما می دانیم که ماژول ما دارای کد آشفته و شلوغ کاری است بنابراین ما به خودمان می‌گوییم که اوه من باید این را با کامنت ها بهتر کنم! نه!! شما باید آن را تمیز کنید. کد خوانا و شفاف با کامنت کم، به مراتب بهتر از کد پیچیده با تعداد کامنت های زیاد است. به جای صرف وقت برای نوشتن کامنتی که توضیح دهنده کدی است که شما ایجاد کرده اید، زمان و انرژی را صرف نوشتن کد تمیز کنید.
منظور خودتان را درون کد توضیح دهید
مطمئنا زمان هایی وجود دارد که کد وسیله ای ضعیف برای بیان توضیحات می‌باشد. متاسفانه برخی از برنامه نویسان این را بدین معنا می‌دانند که کد به ندرت ابزاری خوب برای توضیح دادن است. این به وضوح غلط است. کدامیک از اینها از نظر شما بهتر است ؟
این:
یا این:
تنها چند ثانیه طول می‌کشد که فکر کنید و مقصود خود را بیشتر در کد توضیح دهید. در بسیاری از موارد کاری را که میخواهید در کامنت بگویید به سادگی با ایجاد یک تابع میتوان بیان کرد.
برای مطالعه قسمتی از فصل 2 : نام های معنی دار بر روی لینک کلیک کنید. ( لینک )
