توضیحات تک خطی با // و چند خطی با /* در زبان بَرنامه نویسی سی شارپ (c#.net)
موقعی کِه کُد یک نرم افزار را می نویسید،باید بدونین کِه شُما یا شخص دیگَری در آینده ممکنه بخواهد این کُد را تغییر بده . بنابَراین وظیفه شُماست کِه تا جایی کِه ممکنه کُد را قابل فهم کنین .
توضیحات قِسمتی از بَرنامه می باشدند کِه توسط compiler (کامپایلر) سی شارپ نادیده گرفته می شوند . یعنی شُما میتونین در این بخش از بَرنامه،هر چه میخواهید و به هر زبانی کِه میخواهید بن ویسید و نیازی نمی باشَد کِه قواعد خاصی را رعایت نمایید . این بخش فَقط به بَرنامه نویسی کِه در حال مطالعه کُد بَرنامه می باشد کمَک میکنه تا راحتتر بفهمه اون بخش از بَرنامه در حال چه کاری می باشد .
توجه داشته باشین: همه زبانها قابلیت نوشتن توضیحات را دارند،اما نوع مشخص کردن توضیحات در زبانهای مختلف متفاوت می باشد .
اما سوال اینجاست کِه شُما چه موقع به نوشتن توضیحات نیاز دارین؟ خوب،این مورد بر حسب موقعیتهای مختلف فرق میکنه،اما به عنوان یک قانون کلی میتونیم بگیم کِه بهتر می باشد به اَلگوریتم خودتون دقّت کنین . بَرنامه ای کِه در “پروژه بسازید” بخش پیش نوشتیم دارای اَلگوریتم زیر بود:
1- یک مِقدار را بَرای intNumber تَعریف کن .
2- مِقدار 1 را به intNumber اضافه کن.
3- مِقدار جدید intNumber را به کاربر نشان بده.
می توانید توضیحات را به کُد بَرنامه قَبلی بیفزایید تا با بخش های اَلگوریتم هماهنگ بشود :
int intNumber;
//Set the initial value
intNumber = 27;
//Add 1 to the value of intNumber
intNumber = intNumber + 1;
//Display the new value of intNumber
MessageBox.Show(
"Value of intNumber + 1 = " + intNumber,
"Variables");
در سی شارپ ، توضیحات خود را با دو character اسلش (//) شروع کنین . هر متنی کِه بعد از این دو character تا انتهای اون خط،قرار بگیرد به عنوان توضیح در نظر گرفته خواهد شد . بنابَراین،حتی اگه در یک خط کدی وجود داشته باشه و شُما در اواسط خط از // استِفاده کنین،متن بعد از اون به عنوان توضیح در نظر گرفته میشه. مثل :
این مورد منطقی هم می باشد،به دلیل اینکه فَقط توضیحات بعد از علامت //قرار می گیرند . توجه نمایید کِه توضیحات کُد قَبلی،کم و بیش شبیه اَلگوریتم بَرنامه می باشدند ی. ک تکنیک خوب بَرای اضافه نمودن توضیح به بَرنامه این می باشد کِه اون بخش از اَلگوریتم بَرنامه کِه در حال نوشتن کُد اون می باشین را در چند کلمه توضیح بدین .
اگر در بخشی از بَرنامه نیاز داشتید کِه از بیش از یک خط توضیح استِفاده کنین،میتونین به جای اینکه در ابتدای هر خط از // استِفاده کنین،در جایی کِه توضیحات شروع می شوند از علامت */ استِفاده کنین. به این صورت سی شارپ تموم متن بعد از این علامت را تا موقعی کِه به علامت /* برسد به عنوان توضیح در نظر می گیره. مثلا می توانستیم تموم توضیحات نوشته شده در بَرنامه قَبلی را در یک بخش به صورت زیر وارد کنیم:
2) Set the initial value
3) Add 1 to the value of intNumber
4) Display the new value of intNumber */
int intNumber;
یکی دیگه از روش های تولید بلاکهای توضیحات بَرای متوده ای بَرنامه،استِفاده از ویژگی درونی Document XML Comment در visual studio می باشد . بَرای استِفاده از این ویژگی،مکان نما را در خط خالی بالای متود مورد نظرتان قرار بدین و سه character اسلش (///) تایپ کنین. یک بلاک توضیحات،مثل کُد زیر،به صورت خودکار نشان داده میشه .
اما نکته ای کِه در مورد این ویژگی جالب است،این می باشد کِه visual studio مقادیر مربوط به قسمت name را در این بلاکها بر اساس نام متغیّر های متود شُما کامل میکنه . اگه در متود هیچ پارامتری نداشته باشین ، بخشاز این بلاک توضیحات حذف میشه.
موقعی کِه این بلاک توضیحات را ایجاد نمودید،میتونین یک خلاصه از عملکرد متود را در بخش summary وارد کنین و یا هر توضیح اضافی کِه پیش از فرا خوانی متود باید در نظر داشت را نیز در این بلاک بنویسین . اگه متود شُما مِقداری را بر گرداند قسمت هم به این بلاک اضافه میشه کِه میتونین در رابطه با مِقدار بازگشتی از متود،در اون توضیحاتی بنویسین .
توضیحات داخل بَرنامه عموماً بَرای درک بهتر کُد مورد استِفاده قرار می گیرند،چه بَرای یک بَرنامه نویس کِه تاحالا کُد شُما را ندیده می باشد چه بَرای شُما اگه مدت زمان طولانی کُد را مرور نکرده باشین و اکنون بخواهید اون را تغییر بدین . در کل توضیحات به نکاتی راجع به بَرنامه اشاره می کنن کِه در نگاه اوّل به کُد مشخص نمی باشَدند و یا در مورد عملکرد کُد خلاصه ای را بیان میکنَند تا بَرنامه نویس بتونه بدون دنبال کردن خط به خط کُد از عملکرد اون بخش مطلع شود .
به زودی متوجه خواهید شد کِه هر بَرنامه نویس روش های خاص خودتونش را بَرای توضیح نوشتن داره . اگه شُما بَرای یک شرکت بزر گ کار میکنین،یا مدیر شُما بر کُدنویسی استانداره تاکید داشته باشه،به شُما گفته میشه کِه توضیحات خودتون را در چه قالبهایی بنویسین و یا اینکه در کدام بخش از کُد توضیح بنویسین و در کدام بخش ننویسید.