یک کامنت (comment) یک خط (یا چندین خط) متن است که داخل کد قرار می گیرد تا توضیحاتی را در مورد کاری که آن کد انجام می دهد در بر داشته باشد. در زبان برنامه نویسی ++C دو نوع کامنت (comment) وجود دارد. وقتی خطی کامنت گردد، کامپایلر ++C آن را نادیده گرفته و بخشی از کد برنامه به حساب نخواهد آورد.





نماد // که برای ایجاد کامنت های تک خطی در زبان ++C کاربرد دارد. برای مثال :

std::cout << "Hello world!" << std::endl; // Everything from here to the right is ignored.

معمولاً، کامنت های تک خطی برای درج یک نظر سریع و کوتاه در مورد یک خط از کد، استفاده می شوند.

std::cout << "Hello world!" << std::endl; // cout and endl live in the iostream library

std::cout << "It is very nice to meet you!" << std::endl; // these comments make the code hard to read

std::cout << "Yeah!" << std::endl; // especially when lines are different lengths

قرار دادن کامنت ها در سمت راست کد، موجب می شود تا خواندن کد و همینطور خواندن کامنت مربوطه سخت تر شود. مخصوصاً زمانی که کد شما طولانی باشد، این مشکل بیشتر خودش را نشان خواهد داد. در نتیجه، معمولا نماد کامنت های تک خطی (//) در بالای خط مربوطه قرار داده می شود.

// cout and endl live in the iostream library

std::cout << "Hello world!" << std::endl;

// this is much easier to read

std::cout << "It is very nice to meet you!" << std::endl;

 // don't you think so?

std::cout << "Yeah!" << std::endl;

یک جفت نماد */ و /* برای ایجاد کامنت های چند خطی مورد استفاده قرار می گیرند. همه چیزهایی که مابین این دو نماد قرار بگیرند، کامنت در نظر گرفته می شوند.

/* This is a multi-line comment.

   This line will be ignored.

   So will this one. */

از آنجا که همه متن های داخل این دو نماد، کامنت در نظر گرفته می شوند، برنامه نویسان از این نوع کامنت برای درج توضیحاتی که بیش از یک خط باشند، استفاده می کنند، کامنت های چند خطی به شکل زیر نیز نوشته می شوند :

/* This is a multi-line comment.

 * the matching asterisks to the left

 * can make this easier to read

 */

کامنت های چند خطی نمی توانند به صورت تو در تو نوشته شوند، بنابراین کد زیر ممکن است نتایج غیر منتظره ای را در پی داشته باشد :

/* This is a multi-line /* comment */ this is not inside the comment */

// The above comment ends at the first */, not the second */

استفاده مناسب و صحیح از کامنت ها

معمولاً کامنت ها برای سه منظور مورد استفاده قرار می گیرند. در مورد یک کتابخانه کد، برنامه، و یا یک تابع، بهتر است از کامنت ها برای توصیف آن چیزی که کتابخانه مربوطه، برنامه مربوطه و یا تابع مربوطه انجام می دهند، استفاده شوند. بعنوان مثال :

// This program calculate the student's final grade based on his test and homework scores.

// This function uses newton's method to approximate the root of a given equation.

// The following lines generate a random item based on rarity, level, and a weight factor.

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

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

/* To calculate the final grade, we sum all the weighted midterm and homework scores

    and then divide by the number of scores to assign a percentage.  This percentage is

    used to calculate a letter grade. */

// To generate a random item, we're going to do the following:

// 1) Put all of the items of the desired rarity on a list

// 2) Calculate a probability for each item based on level and weight factor

// 3) Choose a random number

// 4) Figure out which item that random number corresponds to

// 5) Return the appropriate item

کامنت هایی که به این شکل در لابلای کدها قرار می گیرند، به خواننده کد کمک می کنند تا بدون وارد شدن به جزئیات دقیق تر، بتوانند به سادگی در مورد چگونگی عملکرد کد مربوطه مطلع گردند.

کامنت هایی که در سطح بیانیه ها (statement) نوشته می شوند، معمولاً توصیف می کنند که چرا کد مربوطه کار خاصی را انجام می دهد. یک کامنت در سطح بیانیه (statement) اگر بیان کند که کد چه کار می کند، کامنت خوب و مناسبی نخواهد بود. اگر کدی نوشته اید که که آنقدر پیچیده می باشد که باید در کامنت آن توضیح دهید که آن بیانیه (statement) چه کاری را انجام می دهد، احتمالاً نیاز دارید تا کد خود را مجدداً بررسی و یا حتی بازنویسی کنید، نه اینکه برایش توضیحات تکمیلی بیاورید.

در اینجا چند نوع کامنت گذاری خوب و بد را با هم مقایسه می کنیم.

کامنت بد و نامناسب :

// Set sight range to 0

sight = 0;

دلیل اینکه کامنت بالا، کامنت خوبی نمی باشد، اینست که ما در کد به وضوح می توانیم ببینیم که مقدار 0 به متغیر sight نسبت داده شده است.

کامنت خوب :

// The player just drank a potion of blindness and can not see anything

sight = 0;

در کامنت بالا ما می دانیم که چرا مقدار متغیر sight (که بینایی یک بازیکن را در خود دارد) با عدد 0 مقدار دهی شده است.

کامنت بد :

// Calculate the cost of the items

cost = items / 2 * storePrice;

شما در کد می توانید ببینید که یک محاسبه هزینه انجام شده است، اما چرا متغیر items بر عدد 2 تقسیم شده است؟

کامنت خوب :

// We need to divide items by 2 here because they are bought in pairs

cost = items / 2 * storePrice;

الان با این کامنت، ما می دانیم که چرا این تقسیم بر 2 صورت پذیرفته است.

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

کامنت خوب :

// We decided to use a linked list instead of an array because

// arrays do insertion too slowly.



// We're going to use newton's method to find the root of a number because

// there is no deterministic way to solve these equations.

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

خلاصه شده این موارد به شکل زیر بیان می شوند :

• در سطح کتابخانه های کد، برنامه ها یا توابع، توضیح بدهید که چه کاری انجام می شود؟
  
• در داخل کتابخانه های کد، برنامه ها و توابع توضیح بدهید که چگونه انجام می شود؟
  
• در سطح بیانیه ها توضیح بدهید که چرا انجام می شود؟
  

تبدیل کدها به کامنت

تبدیل یک یا چند خط کد به کامنت، راه مناسبی برای تست موقت برنامه می باشد. شما به صورت موقتی می توانید بخشهایی از کدهایتان را کامنت کنید تا تاثیر نبود آنها را بسنجید.

اگر می خواهید فقط یک خط از کدها را به کامنت تبدیل کنید، به سادگی در ابتدای آن خط کد نماد // را قرار بدهید :

خط زیر را در نظر بگیرید.

  std::cout << 1;

حالا این خط تبدیل به کامنت شده است.

//    std::cout << 1;

برای اینکه یک بلوک از کدها را تبدیل به کامنت کنید، می توانید در ابتدای هر خط از آن بلوک کدها، نماد // را قرار بدهید، و یا اینکه با نمادهای */ و /* همه آن بلوک را به صورت موقتی به کامنت تبدیل کنید.

بلوک کد زیر را در نظر بگیرید.

    std::cout << 1;

    std::cout << 2;

    std::cout << 3;

کامنت شده بلوک کد بالا با نماد // به صورت خط به خط

//    std::cout << 1;

//    std::cout << 2;

//    std::cout << 3;

و یا

/*

    std::cout << 1;

    std::cout << 2;

    std::cout << 3;

*/

دلایل مختلفی که باعث می شود کدهای نوشته شده را به کامنت تبدیل کنید، می توانند شامل موارد زیر باشند :

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

کامنت کردن کدها، یک کار رایج در بین برنامه نویسها می باشد، برای همین خیلی از IDE ها امکانی را به شما می دهند که به سادگی بخشهایی از کد را انتخاب کنید و آنها را با یک دستور کامنت کنید. البته این دستور در محیط های IDE مختلف متفاوت می باشد و بسته به IDE مورد استفاده تان باید دستور کامنت آن را بیابید.

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

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

---

آموزش قبلی : آموزش زبان ++C : ساختار یک برنامه

---

آموزش بعدی : آموزش زبان ++C : متغیرها، مقدار دهی اولیه، انتساب