این مقاله رو چند وقت پیش در لینکدین مطالعه کردم. امروز ترجمه ش کردم و خودم از مطالعه ش کلی لذت بردم. امیدوارم مطالعه و مرور این قوانین برای شما هم مفید باشه و لذت ببرید :)
میخوایم برخی از بهترین روش ها برای نوشتن کامنت های کد رو مرور کنیم. معمولا، کامنت ها فقط باید به سؤالاتی پاسخ بدهند که کد نمی تواند (به عنوان مثال "چرا" این شکلی پیاده سازی شده است و به نظر مبهم می آید). کد خوب باید شفاف و مثل یک نوشته راحت خوانده شود و کامنت ها به عنوان حاشیه نویسی آن عمل می کنند. با این حال، نوشتن کامنت به روش صحیح و معنی دار اغلب نادیده گرفته می شود و به عنوان یک کار ثانویه یا پیش پا افتاده در نظر گرفته می شود. یک نظر ضعیف یا مبهم می تواند خواننده کد را گیج یا گمراه کند و باعث آسیبی به مراتب بیشتر از عدم اظهار نظر شود.
بریم قوانین نوشتن Commend در کد رو مرور کنیم:
قانون ۱: نظرات نباید کد را تکرار کنند.
نظرات زائد صرفاً وقت گیر هستند. مثل کد زیر:
این کامنت به کسی کمک نمی کند. فقط حواس را پرت می کند.
قانون ۲: نظرات خوب کد نامشخص را توجیه نمی کند.
اگر متوجه شدید که برای شفاف کردن یک بلوک پیچیده کد کامنت می‌نویسید، صبر کنید. ابتدا کد را بازنگری و اصلاح کنید. نامگذاری خوب متغیر و نوشتن کد شفاف، اغلب نیاز به نظرات را برطرف می کند.
قانون ۳: اگر نمی توانید یک نظر واضح بنویسید، ممکن است کد مشکل داشته باشد.
اگر نمی توانید یک نظر واضح و شفاف برای یک تکه کد بنویسید، ممکن است یک زنگ خطر باشد. شاید کد خیلی پیچیده یا منطق خیلی درهم است. آن را بازنویسی کنید.
قانون ۴: نظرات باید سردرگمی را از بین ببرند، نه اینکه باعث آن شوند.
اجازه ندهید نظرات شما تبدیل به معما شود. اگر یک نظر بیشتر از پاسخ دادن سوال ایجاد کند، نظر خوب و مفیدی نیست.
قانون ۵: کد غیرمعمول را در کامنت توضیح دهید.
گاهی اوقات باید قوانین معمول را برای موارد خاص زیر پا بگذارید. مثلا به شکل عجیبی رفتاری را در کد پیاده سازی کردید که لازم است ولی فقط شما میدانید چرا! وقتی این کار را کردید، دلیل آن را توضیح دهید. یک نظر خوب می تواند مانع از این شود که برنامه نویسان دیگری که در آینده سراغ کد شما می آیند، آنها را صرفا به خاطر اینکه متوجه دلیل نحوه پیاده سازی شما نمی شوند، تغییر بدهند.
قانون ۶: اگر کد را از جایی کپی کردید، لینک منبع را ارائه دهید.
اگر در حال برداشتن کد از Stack Overflow یا هر منبع دیگری هستید، یک پیوند ارائه دهید. می تواند به برنامه نویسانی که بعدا سراغ کد شما می آیند کمک کند.
قانون ۷: به مرجع خارجی لینک بدهید.
اگر کد شما به یک استاندارد خاص پایبند است یا به یک RFC پاسخ می دهد، این را در یک کامنت بگویید و به آن مرجع لینک بدهید.
قانون ۸: بعد از رفع اشکال، کامنت بگذارید.
هنگامی که یک باگ را برطرف می کنید، یک کامنت کوچک برای توسعه دهندگان بعدی بگذارید. این ممکن است یک کامنت خیلی ساده باشد که رفتار باگ را توضیح میدهد یا به شماره باگ گزارش شده ارجاع میدهد.
قانون ۹: از کامنت ها برای علامت گذاری پیاده سازی های ناقص استفاده کنید.
گاهی اوقات باید کدی را پیش از اینکه تکمیل شود، commit کنید. از یک قالب استاندارد TODO برای برجسته کردن این موارد استفاده کنید. بدهی فنی (موارد باقی مانده) را ذکر کنید و یا به یک issue tracker ارجاع دهید.
نتیجه
کامنت ها، اشتباهات پیاده سازی را اصلاح نمی کنند. آنها مانند مکمل کدهای خوب عمل میکنند. وقتی کامنت مبهم بنویسیم، کد هم مبهم میشود. این دستورالعمل ها را در ذهن داشته باشید.
لینک مقاله رو اینجا میگذارم.
موفق باشید :)
