CSharp Comments and Documentation Practices

هنتكلم النهاردة عن الـ Comments و الـ Documentations

الكومنتات أو التعليقات مهمة جدًا عشان تخلي الكود بتاعك مفهوم أكتر، سواء ليك بعد فترة أو لأي حد تاني بيقرا الكود ده. فيه كذا طريقة نكتب بيها كومنتات في C#.

1. Single-line Comments

• ده أبسط نوع، زي اللي بنستخدمه في لغات زي C++ بالظبط.
• بنستخدم علامتين slash //.
• أي كلام بيجي بعد // في نفس السطر، الكومبايلر بيتجاهله تمامًا ومبيعتبرهوش جزء من الكود.

// This is a comment explaining the next line
Console.WriteLine("Hello World!");
 
Console.WriteLine("Hello World!");  // This comment is at the end of the line

2. Multi-line Comments

• لو عايز تكتب كومنت طويل شوية واخد كذا سطر، بنستخدم الطريقة دي.
• بتبدأ الكومنت بـ /* وبتنهيه بـ */.
• كل الكلام اللي بيتكتب بين العلامتين دول، حتى لو كان واخد سطور كتير، بيعتبره الكومبايلر كومنت.

/*
This is a multi-line comment.
The code below will print the words Hello World
to the screen, and it is amazing.
You can write as many lines as you want here.
*/
Console.WriteLine("Hello World!");

3. Documentation Comments

• دي بقى الطريقة الاحترافية والأهم، خصوصًا في المشاريع الكبيرة أو لما بتكون شغال في فريق عمل، أو بتعمل API أو Library Programming حد تاني هيستخدمها.

• النوع ده من الكومنتات مش مجرد شرح عادي، لأ ده طريقة منظمة وموحدة (standard) عشان توصف الـ Classes والـ Methods والـ Properties بتاعتك بتعمل إيه بالظبط.

• ليه مهمة؟

  • بتخلي الكود سهل القراءة والفهم جدًا.
  • بتساعد أي حد جديد في الفريق يفهم الكود بسرعة من غير ما يحتاج يسأل كتير.
  • بتسهل عملية صيانة وتعديل الكود في المستقبل.
  • بتستخدمها أدوات زي Visual Studio عشان تظهرلك مساعدة IntelliSense وانت بتكتب الكود.
  • ممكن نولّد منها ملفات Documentation للمشروع بشكل تلقائي (زي ملفات HTML أو غيرها).

• بنكتبها إزاي؟ بنستخدم ثلاث علامات slash /// قبل الـ Class أو الـ Method أو الـ Property اللي عايزين نوصفه.

• الميزة: أول ما بتكتب /// فوق أي Method مثلًا في Visual Studio، هو لوحده بيكملك الهيكل الأساسي بتاع الكومنت بالـ XML tags المشهورة.

• أشهر الـ Tags اللي بنستخدمها جواها:

  • الـ <summary>: بتكتب فيها ملخص سريع ومختصر الـ Method دي بتعمل إيه.
  • الـ <param name="parameterName">: بتستخدمها مرة لكل parameter الـ Method بتاخده. بتكتب اسم الـ parameter وتشرح هو بتاع إيه.
  • الـ <returns>: بتوصف فيها القيمة اللي الـ Method دي بترجعها (لو مش void).
  • فيه tags تانية زي <remarks> (ملاحظات إضافية), <exception> (لو بترمي exception معين), <example> (مثال لاستخدامها).
  • تفاصيل أكتر عن الـ tags دي ممكن تلاقيها هنا: XML Documentation Comments

• مثال عملي:

/// <summary>
/// Calculates the sum of two integers.
/// </summary>
/// <param name="a">The first integer to add.</param>
/// <param name="b">The second integer to add.</param>
/// <returns>
/// The sum of the two integers.
/// </returns>
/// <remarks>
/// This is a very simple method just for demonstration.
/// </remarks>
public static int AddNumbers(int a, int b)
{
    // Check for potential overflow if necessary (not done here for simplicity)
    return a + b;
}
 
public static void Main(string[] args)
{
    // When you type AddNumbers(, IntelliSense will show the summary and parameter info
    int result = AddNumbers(5, 10);
    Console.WriteLine($"The sum is: {result}");
}

• لما تيجي تستخدم الـ Method دي (AddNumbers) في مكان تاني في الكود، الـ IntelliSense في Visual Studio هيعرضلك الـ summary والشرح بتاع الـ parameters اللي انت كتبته في الـ /// comments، وده بيسهل الاستخدام جدًا.