<p style="text-align: justify;">نوشتن توضیحات یا Comment در تمام زبان های برنامه نویسی مرسوم است. برنامه نویس ها معمولاً برای خواناتر شدن کدهای خود توضیحات می نویسند، اما در برخی مواقع به طور خواسته یا ناخواسته این توضیحات به جای اینکه سودمند باشند آزاردهنده می شوند. در این مطلب نکاتی ذکر خواهد شد که با بکار بستن آن ها می توان توضیحاتی خوانا و قابل درک در برنامه ها نوشت.</p>
<p style="text-align: justify;"><strong>1) توضیحات را مرتب و پشت سر هم بنویسید : </strong>هنگامی که برای چند خط کد به صورت متوالی کامنت می نویسید بهتر است تمام کامنت ها در یک ستون عمودی تراز شوند تا خواناتر به نظر برسند.</p>
<p style="text-align: justify;" dir="ltr">List<User> users = User.GetAll(); <span style="color: rgb(51, 153, 102);">//Get all available users</span><br>
users.Add(aUser); <span style="color: rgb(51, 153, 102);">//Add a User</span></p>
<p style="text-align: justify;"><strong>2) در کوتاه ترین جملات منظور خود را برسانید :</strong> سعی نکنید قضیه را بپیچانید! با کمترین کلمات ممکن منظور خود را برسانید و از نوشتن توضیحات اضافی پرهیز کنید.</p>
<p style="text-align: justify;"><strong>3) بدانید برای چه چیزی توضیح می نویسید :</strong> نوشتن کامنت برای یک کلاس با نوشتن کامنت برای یک پراپرتی یا یک متد فرق می کند. برای یک کلاس شما باید یک خلاصه توضیحات، نام نویسنده و تاریخ آخرین تغییر را بنویسید و کاری را که این کلاس قرار است انجام بدهد را مشخص کنید. برای یک متد شما باید علاوه بر نوشتن یک توضیح خلاصه، توضیحی در مورد هر یک از پارامترهای متد و نوع خروجی متد بنویسید.</p>
<p style="text-align: justify;"><strong>4) به شعور خواننده توهین نکنید! :</strong> از توضیح بدیهیات پرهیز کنید. نوشتن توضیحاتی شبیه به توضیحات زیر را کنار بگذارید :</p>
<p style="text-align: justify;" dir="ltr">if(CanSave == true)<span style="color: rgb(51, 153, 102);"> //if User can Save</span><br>
SaveToFile(); <span style="color: rgb(51, 153, 102);">//then Save it to file!</span></p>
<p style="text-align: justify;">نوشتن این گونه توضیحات به جز اینکه وقت شما و خواننده کد را بگیرد، هیچ سود دیگری ندارد.</p>
<p style="text-align: justify;"><strong>5) از یک استاندارد مشخص پیروی کنید : </strong>مخصوصاً وقتی با یک تیم برنامه می نویسید این مورد را حتماً رعایت کنید. کامنت کردن کدها بر اساس استاندارد و استفاده از ابزارهای مربوطه بسیار توصیه می شود. به طور مثال در C# استفاده از توضیحات XML مرسوم است و کار شما را آسان می کند.</p>
<p style="text-align: justify;"><strong>6) توضیحات را همزمان با نوشتن کد بنویسید : </strong>زمانی که شروع به کد نویسی می کنید ذهن شما بر روی مسئله جاری متمرکز شده است و بهترین زمان برای نوشتن توضیحات در مورد کد مورد نظر است. اگر نوشتن توضیحات را به زمان دیگری موکول کنید ممکن است توضیحاتی که بعداً می نویسید همانی نباشد که در ابتدا در ذهن شما بوده است.</p>
<p style="text-align: justify;"><strong>7) طوری توضیحات بنویسید که دوست دارید دیگران برای شما بنویسند! :</strong> موقعیتی را در نظر بگیرید که باید کدهای کلاسی که یک برنامه نویس دیگر نوشته است را تغییر دهید و کدهای نوشته شده هم آنقدر ناخواناست که بدون خواندن توضیحات نمی توانید از آن ها سر در بیاورید. اگر آن برنامه نویس توضیحات خوانایی برای این کدها ننوشته باشد کار شما برای تغییر کدها بسیار سخت خواهد بود. پس طوری کامنت بنویسید که برنامه نویس بخت برگشته ای که بعد از شما م