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

کامنت گذاری در برنامه نویسی را می توان به دو روش انجام داد.

اولین نوع که به سبک زبان C است و توسط ++C نیز به ارث برده شده است. این نوع کامنت گذاری با */ شروع می شود و می تواند چندین خط ادامه داشته باشد و سرانجام با /* خاتمه پیدا می کند.

تعداد زیادی از برنامه نویسان برای زیبایی بیشتر، هر خط توضیح را با * شروع می کنند. مثال زیر نمونه ای از این نوع کامنت گذاری است.

دومین روش استفاده از // برای توضیحات یک خط می باشد

بهترین روش بخش توضیحات ( comments و javadoc )

توضیحات به سه فرم نوشته می شود.

♦ در حالت اول توضیحاتی برای یک کلاس یا متد یا فیلد می نویسیم، این توضیحات با استفاده از ابزارهایی نظیر javadoc generator به فایلهای html تبدیل شده و مانند یک کتاب الکترونیکی به سایر برنامه نویس ها در فهمیدن و استفاده از کد کمک می کند، نظیر آن چیزی که در اکثر راهنماها در اینترنت قابل مشاهده است. مثال:

1. /**
2. * Here is a block comment with some very special
3. * formatting about your class
4. * you can use html tags like some bold text
5. * one
6. * two
7. * three
8. */
9. publicstaticMyClass{
10.  
11. }

♦ حالت دوم برای زمانی است که می خواهیم برای یک قسمت از کد توضیحات تکمیل تری بنویسیم، این توضیحات در javadoc درج نمی شوند و برای خواننده کد قابل دیدن هستند. مثال:

1. 
   /*
2. * Here is a block comment for some parts of code
3. */

♦ حالت سوم برای توضیح یک خط از کد است که نیاز به چند سطره شدن ندارد. معمولاً از این روش بیشتر برای غیر فعال کردن خطوط کد استفاده می شود. مثال:

1. 
   if(foo >1){
2. // Do a double-flip.
3. ...
4. }else{
5. returnfalse;// Explain why here.
6. }
7.  
8. //if (bar > 1) {
9. // // Do a triple-flip.
10. // ...
11. //} else {
12. // return false;
13. //}