نظر کوتاه من در مورد اینکه چرا باید از کامنت ها در کد خود جلوگیری کنید (مگر در موارد خاص)

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

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

[متن در تصویر: این یک علامت توقف است]
[متن در تصویر: این یک علامت توقف است]

منبع: برنامه نویسان میم توییتر

این عکس بهترین نظر در مورد افزودن کامنت به کد است. کاش می شودم بگویم اغراق آمیز است. اما چه تفاوتی بین عکس بالا و کامنت تابع زیر است؟

// function to count the perimeter of the triangle
// input: 3 numbers, output: number
const countTrianglePertimeter = (a: number, b: number, c: number)
: number => {
    return a + b + c;
}

متأسفانه، ما هنوز هم می‌توانم تکه‌های زیادی از این قبیل را در کد پیدا کنیم. و من شدیداً شما را تشویق می کنید که از آنها دوری کنید! چرا؟ تعداد زیادی برای توقف اضافه کردن کامنت‌های بیهوده به کد شما وجود دارد.

سایر کامنت‌ها هیچ اطلاعات دیگری در اختیار کاربر قرار نمی‌دهند. آنها دقیقاً همان چیزهایی را توصیف می کنند که کد انجام می دهد. پس چرا اطلاعات را برای تکرار کنیم؟ به جای آن از نام های معنی دار استفاده کنید. در صورت نیاز منطق را به متدهای بررسی کنید. Content را به تغییرات const با نام خوب استخراج کنید. به عنوان مثال ساده کد. اگر نیاز داشتید از بازگشت زود هنگام (Return Early Pattern) و دوری از تورفتگی چندگانه استفاده کنید. خواندن کدهای خوب نوشته شده توسط انگلیسی زبانان غیر بومی آسان تر از توضیحات به زبان ساده است!

کد در پروژه های زنده تغییر می کند. همیشه برخی رفع اشکال یا عملکردهای جدید وجود دارد که نه تنها نیاز به کد افزودن دارد، بلکه ویرایش کد موجود نیز دارد. و تا زمانی که کد همیشه به روز باشد، به کسی که در مورد روز کردن کامنت‌ها چیزی به یاد می‌آورد نیست. بنابراین، کامنت‌ها قدیمی هستند و کد قدیمی را ارائه می‌دهند. به یاد داشته باشید، کامنت‌ها می‌توانند دروغ بگویند کد هرگز این کار را نمی کند!

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

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

گاهی اوقات محض احتیاط ما کد را کامنت می‌کنیم تا در آینده مفید واقع شود. اما بیایید صادق باشیم — هیچ چیز ترسناک‌تر از کدی وجود ندارد که کامنت شده است و هیچ دلیلی آن را نمی‌داند. آیا می کنم فقط آن را حذف کنیم؟ چرا کار نمی کند؟ اگر آن را از کامنت خارج کنیم چه اتفاقی می افتد؟ ناتمام یا «تقریباً کار می کند» اسنیپت هایی را گذاشت که در کد کامنت شده و می توانم سال ها پیش مفید باشد. اما اکنون ما نسخه‌های عالی کد مانند git داریم — حذف کد با پیام کامیت معنی‌دار و توصیفی (و در نهایت اضافه کردن یک برچسب برای آسان‌تر یافتن آن در آینده) بسیار راحت‌تر، واضح‌تر و آسان‌تر برای بازگرداندن آن است. همچنین، تقریباً هیچ کس شروع به پیاده‌سازی یک ویژگی جدید با جستجوی کدهای کامنت شده در پایگاه کد نمی‌کند. بنابراین احتمال اینکه از کدهای غیرضروری فعلی شما استفاده شود بسیار کم است.

در قسمت قبل از شهروندی برای حذف کامنت‌ها از کد شما توضیح دادم. با این حال، موارد خاصی وجود دارد که کامنت‌ها می‌توانند مفید باشند — حتی در کد پروداکشن! آنها در زیر توضیح داده شده اند — اما به یاد داشته باشید: من آنها را تصادفی موارد خاص نمی نامم 🙂

ضرب المثلی قدیمی وجود دارد که می گوید: «اگر مشکلی دارید و برای حل آن از regex استفاده می کنید، پس دو مشکل دارید». عبارات باقاعده عالی و مفید هستند، اما متأسفانه به خواندنی می گویند. به همین دلیل است که کامنت‌هایی را اضافه می‌کند که توضیح می‌دهند یک regex چه چیزی را بررسی می‌کند بدترین ایده نیست.

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

روند توسعه به مراحل تقسیم می شود. و اشکالی ندارد که همه تغییرات را در یک ارتکاب در نظر بگیرید، بلکه باید موارد بعدی را انجام دهید. وقتی پروژه شما کوچک است و از هیچ ابزاری برای ردیابی وظایف استفاده نمی کنید (مثل جیرا یا مسائل Github)، داشتن کامنتهای TODO که می گوید چه چیزی باید تغییر کند و کجا، می تواند مفید باشد. به خصوص به این دلیل که ویرایشگرهای کد مکانیسم دارای خاصیت پشتیبانی از آنها هستند. اینجاست که این راه حل حل پذیر نیست و می تواند برای پروژه های بزرگ ناکارآمد باشد.

برخی از نکات ممکن است به شما در تصمیم گیری در مورد نیاز به کامنت ها یا نحوه استفاده صحیح از آنها کمک کند. اول از همه، قبل از نوشتن کامنت، اگر همان محتوا را در کد ارائه کنید. چرا برای بیان قصد خود به متن نیاز دارید؟ چرا کد نمی تواند خودش صحبت کند؟ اغلب اوقات نیاز به نوشتن کامنت فقط نشانه ای از نیاز به ریفکتور است. همچنین، اگر مجبور به نوشتن کامنت هستید (به دلیل یکی از مواردی که در قسمت قبل توضیح داده شد)، کامنت خود را تا حد امکان نزدیک به کدی که آن را توصیف می‌کند نگه دارید. اگر افکار خود را در فایل‌های ابتدایی اضافه کنید، شخصی که کد را می‌خواند احتمالاً متوجه آن نمی‌شود یا در حین پیاده‌سازی برخی تغییرات آن را به روز نمی‌کند. و صحبت در مورد تغییرات آنها را در سورس کد ردیابی نکنید. Git واقعا مکان بهتری برای ردیابی تغییرات است و نویسندگانشان. همچنین، git (یا هر سیستم کنترل ورژن دیگری) دوست شماست اگر می‌خواهید برخی از قابلیت‌ها را حذف کنید اما فرصتی برای برگرداندن آن داشته باشید. در سورس کد کامنت نکنید — به جای آن یک commit با یک نام معنادار ایجاد کنید و برنامه نویسان در صورت نیاز آن را در تاریخچه خواهند کرد. با تشکر از همه این نکات، کد شما برای همه تمیزتر، به روزتر و خواندن تر خواهد بود.

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

https://dev.to/this-is-learning/a-short-comment-on-comments-in-the-code-1i54



اگر دوست داشتی امتیاز دادن یادت نره!