10 نکته برای نوشتن بهتر توضیحات در سورس کد


نوشتن توضیحات یا Comment در تمام زبان های برنامه نویسی مرسوم است. برنامه نویس ها معمولاً برای خواناتر شدن کدهای خود توضیحات می نویسند، اما در برخی مواقع به طور خواسته یا ناخواسته این توضیحات به جای اینکه سودمند باشند آزاردهنده می شوند. در این مطلب نکاتی ذکر خواهد شد که با بکار بستن آن ها می توان توضیحاتی خوانا و قابل درک در برنامه ها نوشت.

1) توضیحات را مرتب و پشت سر هم بنویسید : هنگامی که برای چند خط کد به صورت متوالی کامنت می نویسید بهتر است تمام کامنت ها در یک ستون عمودی تراز شوند تا خواناتر به نظر برسند.

List<User> users = User.GetAll(); //Get all available users
users.Add(aUser);                 //Add a User

2) در کوتاه ترین جملات منظور خود را برسانید : سعی نکنید قضیه را بپیچانید! با کمترین کلمات ممکن منظور خود را برسانید و از نوشتن توضیحات اضافی پرهیز کنید.

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

4) به شعور خواننده توهین نکنید! : از توضیح بدیهیات پرهیز کنید. نوشتن توضیحاتی شبیه به توضیحات زیر را کنار بگذارید :

if(CanSave == true) //if User can Save
SaveToFile();       //then Save it to file!

نوشتن این گونه توضیحات به جز اینکه وقت شما و خواننده کد را بگیرد، هیچ سود دیگری ندارد.

5) از یک استاندارد مشخص پیروی کنید : مخصوصاً وقتی با یک تیم برنامه می نویسید این مورد را حتماً رعایت کنید. کامنت کردن کدها بر اساس استاندارد و استفاده از ابزارهای مربوطه بسیار توصیه می شود. به طور مثال در C# استفاده از توضیحات XML مرسوم است و کار شما را آسان می کند.

6) توضیحات را همزمان با نوشتن کد بنویسید : زمانی که شروع به کد نویسی می کنید ذهن شما بر روی مسئله جاری متمرکز شده است و بهترین زمان برای نوشتن توضیحات در مورد کد مورد نظر است. اگر نوشتن توضیحات را به زمان دیگری موکول کنید ممکن است توضیحاتی که بعداً می نویسید همانی نباشد که در ابتدا در ذهن شما بوده است.

7) طوری توضیحات بنویسید که دوست دارید دیگران برای شما بنویسند! : موقعیتی را در نظر بگیرید که باید کدهای کلاسی که یک برنامه نویس دیگر نوشته است را تغییر دهید و کدهای نوشته شده هم آنقدر ناخواناست که بدون خواندن توضیحات نمی توانید از آن ها سر در بیاورید. اگر آن برنامه نویس توضیحات خوانایی برای این کدها ننوشته باشد کار شما برای تغییر کدها بسیار سخت خواهد بود. پس طوری کامنت بنویسید که برنامه نویس بخت برگشته ای که بعد از شما می خواهد کدها را تغییر دهد عذاب نکشد! با این کار اول خودمان سود خواهیم کرد، زیرا ممکن است اولین نفری باشیم که در آینده می خواهیم کدهای خودمان را تغییر دهیم.

8 ) با تغییر کدها، توضیحات را تغییر دهید : همیشه کامنت ها را به صورت موازی با کدهای خود تغییر دهید. اگر کدهای خود را تغییر دهید اما توضیحاتش را آپدیت نکنید، به جای اینکه این توضیحات در آینده سودمند باشند، نگهداری کد را سخت تر خواهند کرد. نداشتن توضیحات در سورس کد بهتر از داشتن توضیحات غلط در آن است. حواستان به ابزارهای Refactoring باشد که کدها را به صورت خودکار تغییر می دهند اما توضیحات را بدون تغییر رها می کنند.

9) از برچسب های معنی دار استفاده کنید : زمانی که در یک تیم کار می کنید، سعی کنید از برچسب های معنی دار و قراردادی بین اعضای تیم برای منظورهای مختلف استفاده کنید. به طور مثال بسیاری از برنامه نویس ها از برچسبی مثل «//TODO :» استفاده می کنند تا مشخص کنند قسمتی از کد نیاز به کار اضافی دارد و یا از برچسبی مثل «Temp» جهت نوشتن کدهای موقت که بعداً باید حذف یا جایگزین شوند استفاده می کنند. شاید برچسب ها توضیحی در مورد کد نباشند، اما به جای آن پیغامی را به شما و دیگر هم تیمی های شما یادآوری می کنند.

10) کد خوب، خودش را توضیح می دهد : همیشه بخاطر داشته باشید که کد خوب بهترین داکیومنت برای خودش است. اگر دوست ندارید یا حوصله ندارید برای کدهایتان کامنت بنویسید بهتر است کدهایی بنویسید که خودشان را توضیح می دهند. برای نوشتن چنین کدهایی باید نام متغیرها، کلاس ها، متدها و پراپرتی ها را کاملاً معنی دار انتخاب کنید. به طور مثال شما نیازی به نوشتن کامنت برای متد زیر ندارید :

AddUserToDatabase(User user)

هر کسی با مشاهده متد بالا متوجه می شود که کار آن اضافه کردن یک کاربر به دیتابیس است.

 

منبع : 13 Tips to Comment Your Code

Advertisements