همه چیز درباره کامنت خوب

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

خلاصه

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

مقدمه

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

منبع: Programmers Memes Twitter

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

// 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;
}

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

دلایلی برای توقف اضافه کردن کامنت ها به کدتان

کامنت ها فقط زائده‌هایی در کد هستند

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

کامنت ها اغلب قدیمی هستند

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

کامنت ها می توانند گمراه کننده باشد

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

کامنت ها سورس کد را طولانی تر می کنند

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

همه از حذف یا خارج کردن کد از کامنت می ترسند

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

موارد خاصی که کامنت ها ممکن است مفید باشند

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

(عبارات باقاعده) RegEx ها

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

منطق تجاری خاص

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

کامنت های TODO

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

نکاتی در مورد کامنت ها و اجتناب از آنها

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

خلاصه

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

منبع

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