كتابة تعليقات

عندما تبدأ بالبرمجة، ستعتاد سريعاً على حقيقة أن أي محرف أو كلمة تدخلها لها معنى خاص. على سبيلا المثال، سترى العديد من (الكلمات الدلالية) keywords في #C مثل (فئة) class ، (فضاء الاسم) namespace، (عام) public، والعديد غيرها. وسترى أيضاً أن المترجم يتأكد من أنك تستعمل تلك الكلمات المفتاحية، بالإضافة إلى متحولاتك وأوامرك، وبالصيغة الصحيحة. وتعد #C لغة صارمة إلى حد ما، لذا يساعدك المترجم للتأكد من أن كل شيء مدخل بالشكل المحدد له. على أي حال، فهناك احتمال وحيد يسمح لك بكتابة ما تشاء، والفضل يعود بذلك إلى فكرة التعليق على الأكواد "Code Comments"..

ربما تكون قد صادفت التعليقات في بعض الأسطر البرمجية التي رأيتها، سواءً في #C أو أي لغة برمجة أخرى - ويعد مفهوم التعليقات في البرمجة عالمياً للغاية. وقد تختلف كثيراً الطرق التي يمكن أن يُكتبوا بها، لذلك سننظر إلى أنواع التعليقات التي يمكنك استخدامها في برمجة #C.

تعليقات وحيدة السطر

يعد التعليق وحيد السطر أحد أبسط أنواع التعليقات في #C. وكما هو موضح في الاسم، فهذا النوع يحول سطراً واحداً إلى تعليق - لنرى كيف سيبدو شكله:

// My comments about the class name could go here...
class Program
{
    ......

بهذه البساطة: ضع خطين مائلين للأمام (//) قبل الأسطر البرمجية، وسيتحول السطر من شيء يهتم به المترجم أو يشتكي حياله، لأمر يتجاهله تماماً. ولأان هذا ينطبق على السطر الذي يسبق أكوادك، فأنت حر أيضا بتطبيقه في السطر التالي، ويستخدم هذا مبدئياً لاستعمال تعليق وحيد السطر لكتابة العديد من أسطر التعليقات.

// My comments about the class name could go here...
// Add as many lines as you would like
// ...Seriously!
class Program
{
    ...... 

تعليق متعدد الأسطر

في حال كنت ترغب بكتابة تعليقات متعددة السطور، فسيكون من المنطقي أكثر أن تستعمل النوع الذي يقدمه #C للتعليق متعدد الأسطر. فبدلاً من إضافة السابقة (//) في كل سطر، تقوم بإضافة محارف معينة في البداية والنهاية، وكل ما يوضع بينهما سيعامل على أنه تعليق:

/*  
My comments about the class name could go here...  
Add as many lines of comments as you want  
    ...and use indentation, if you want to!  
*/  
class Program  
{
    ......

اكتب محرفي البداية وهما خط مائل للأمام ونجمة (*/)، ثم اكتب ما تشاء في سطر واحد أو بعدة أسطر، بعد ذلك انهِ تعليقك باستعمال محرفي النهاية وهما نجمة وخط مائل للأمام (/*). وبين هذه العلامات، يمكنك كتابة كل ما تشاء.

As with pretty much any other programming related subject, whether to use multiple single-line comments or one multi-line comment is often debated. Personally, I use both, for various situations - in the end, it's all up to you!

Documentation comments

Documentation Comments (sometimes referred to as XML Documentation Comments) looks like regular comments, but with embedded XML. Just like with regular comments, they come in two forms: Single-line and multi-line. You also write them the same way, but with an extra character. So, single-line XML Documentation Comments uses three forward slashes (///) instead of two, and the multi-line variant gets an extra asterisk added in the start delimiter. Let's see how it looks:

class User
{
    /// <summary>
    /// The Name of the User.
    /// </summary>
    public string Name { get; set; }

    /**
    * <summary>The Age of the User.</summary>
    */
    public string Age { get; set; }
}

Here you can see both variants - single-line and multi-line. The result is the same, but the first variant tends to be the most commonly used for documentation comments.

Documenting your types and their members with documentation comments is a pretty big subject, and therefore it will be covered more in depth in a later article, but now you know how they look!

التعليق على البرمجة & قائمة المهام "Task List"

If you're using Visual Studio, you can actually get some help tracking your code comments. In the Task List window (access it from the menu View > Task List) your comments will appear if they use the special, but very simple Task List comment syntax:

//TODO: Change "world" to "universe"
Console.WriteLine("Hello, world!");
//HACK: Don't try this at home....
int answerToLife = 42;

فإذا سبق التعليق وحيد السطر مباشرةً تعليمات مثل TODO أو HACK، سيظهر التعليق في قائمة المهام "Task List" في فيجوال ستوديو، مثل التالي:

وهناك عدة أنواع أخرى - وهذا يعتمد على نسخة الفيجوال ستوديو التي تستعملها، فقد تستجيب لبعض أو جميع تعليمات التعليق التالية:

• TODO (لأقوم به لاحقاً)
• HACK (هام/اختراق)
• NOTE (ملاحظة)
• UNDONE (غير مكتمل)

ويمكنك حتى إضافة تعليماتك الخاصة، إذا أردت ذلك - قم بالخطوات المشروحة في هذا المقال.

تلخيص

تعد التعليقات على الأكواد مفيدة جداً في توصيف برمجتك أو لغرض وضع دلائل لنفسك أو لزملائك إن وجد لمعرفة كيف تعمل الأمور. علاوة على ذلك، فإنها عظيمة عندما تود اختبار شيءٍ ما بسرعة - فقط انسخ السطر وحوًل السطر الأساسي إلى تعليق، وسترى إن أصبح يعمل الآن. إن لم تعجبك النتيجة، يمكنك حينها أن تحذف السطر الجديد وتلغي التعليق عن السطر الأساسي هكذا تكون قد عدت إلى ما سبق.

ولا تقلق بشأن تطفل المستخدم النهائي على تعليقاتك - كما ذكرنا سابقًا ، يتم تجاهلها تمامًا من قبل المترجم وبالتالي لا يتم تضمينها بأي حال من الأحوال في ملف DLL أو EXE النهائي. التعليقات على التعليمات البرمجية هي مساحتك الشخصية الخالية عند البرمجة ، لذا استخدمها بأي طريقة تريدها.