تمرين - إنشاء تعليقات تعليمات برمجية فعالة

مكتمل

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

ما هو تعليق التعليمة البرمجية؟

تعليق التعليمة البرمجية: هو إصدار تعليمة للمحول البرمجي بتجاهل كل شيء بعد رموز تعليق التعليمة البرمجية في الخط الحالي.

// This is a code comment!

قد لا يبدو هذا مفيدًا في البداية، ومع ذلك فهو مفيد في ثلاث حالات:

• عندما تريد ترك ملاحظة حول الهدف من مرور التعليمة البرمجية. قد يكون من المفيد تضمين تعليقات التعليمات البرمجية التي تصف الغرض أو عملية التفكير عند كتابة مجموعة صعبة بشكل خاص من تعليمات الترميز. ستشكرك نفسك في المستقبل.
• عندما تريد إزالة التعليمة البرمجية مؤقتًا من التطبيق الخاص بك لمحاولة اتباع نهج مختلف؛ ولكنك لم تقتنع بعد بأن فكرتك الجديدة ستنجح. يمكنك التعليق على التعليمة البرمجية، وكتابة التعليمة البرمجية الجديدة، وبمجرد اقتناعك بأن التعليمة البرمجية الجديدة ستعمل بالطريقة التي تريدها، يمكنك حذف التعليمة البرمجية القديمة (التعليمة البرمجية المعلق عليها) بأمان.
• إضافة رسالة مثل TODO لتذكيرك بالنظر إلى مقطع معين من التعليمات البرمجية لاحقا. في حين أنه يجب عليك استخدام هذا بحكمة، فإنه نهج مفيد. قد تكون تعمل على ميزة أخرى عند قراءة خط من التعليمة البرمجية مما يثير القلق. بدلاً من تجاهل المخاوف الجديدة، يمكنك تمييزها لبحثها في وقت لاحق.

إشعار

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

إعداد بيئة الترميز الخاصة بك

تتضمن هذه الوحدة النمطية تمارين ترشدك خلال عملية إنشاء نموذج التعليمات البرمجية وتشغيله. يتم تشجيعك على إكمال هذه الأنشطة باستخدام Visual Studio Code كبيئة تطوير. سيساعدك استخدام Visual Studio Code لهذه الأنشطة على أن تصبح أكثر راحة في كتابة التعليمات البرمجية وتشغيلها في بيئة مطور يستخدمها المحترفون في جميع أنحاء العالم.

1. فتح Visual Studio Code.

   يمكنك استخدام القائمة Windows (أو مورد مكافئ لنظام تشغيل آخر) لفتح Visual Studio Code.

2. في قائمة Visual Studio Code File ، حدد Open Folder.

3. في مربع الحوار فتح مجلد ، انتقل إلى مجلد سطح مكتب Windows.

   إذا كان لديك موقع مجلد مختلف حيث تحتفظ بمشاريع التعليمات البرمجية، يمكنك استخدام موقع المجلد هذا بدلا من ذلك. لهذا التدريب، الشيء المهم هو أن يكون لديك موقع يسهل تحديد موقعه وتذكره.

4. في مربع الحوار فتح مجلد ، حدد تحديد مجلد.

   إذا رأيت مربع حوار أمان يسألك عما إذا كنت تثق بالمؤلفين، فحدد نعم.

5. في قائمة Visual Studio Code Terminal ، حدد New Terminal.

   لاحظ أن موجه الأوامر في لوحة Terminal يعرض مسار المجلد للمجلد الحالي. على سبيل المثال:

   C:\Users\someuser\Desktop>
   

   إشعار

   إذا كنت تعمل على جهاز الكمبيوتر الخاص بك بدلا من بيئة الاختبار المعزولة أو البيئة المستضافة وأكملت وحدات Microsoft Learn الأخرى في سلسلة C# هذه، فربما تكون قد أنشأت بالفعل مجلد مشروع لعينات التعليمات البرمجية. إذا كان الأمر كذلك، يمكنك تخطي الخطوة التالية، والتي تستخدم لإنشاء تطبيق وحدة تحكم في مجلد TestProject.

6. في موجه الأوامر Terminal، لإنشاء تطبيق وحدة تحكم جديد في مجلد محدد، أدخل المطالبة التالية:

   dotnet new console -o ./CsharpProjects/TestProject
   

   يستخدم أمر .NET CLI هذا قالب برنامج .NET لإنشاء مشروع تطبيق وحدة تحكم C# جديد في موقع المجلد المحدد. ينشئ الأمر مجلدات CsharpProjects وTestProject نيابة عنك، ويستخدم TestProject كاسم لملفك .csproj .

   إذا تم عرض رسالة تخبرك بأن الملفات موجودة بالفعل، فتابع الخطوات التالية. ستقوم بإعادة استخدام ملفات المشروع الموجودة.

7. في طريقة عرض EXPLORER، قم بتوسيع المجلد CsharpProjects .

   يجب أن تشاهد مجلد TestProject وملفين، ملف برنامج C# المسمى Program.cs وملف مشروع C# يسمى TestProject.csproj.

8. في قائمة Visual Studio Code File ، حدد Open Folder.

9. في مربع الحوار فتح مجلد ، حدد المجلد CsharpProjects ، ثم حدد تحديد مجلد.

10. في طريقة عرض EXPLORER، قم بتوسيع المجلد TestProject، ثم حدد Program.cs.

11. حذف أسطر التعليمات البرمجية الموجودة.

    ستستخدم مشروع وحدة تحكم C# هذا لإنشاء نماذج التعليمات البرمجية وبنائها وتشغيلها أثناء هذه الوحدة النمطية.

12. أغلق لوحة Terminal.

إنشاء تعليقات التعليمات البرمجية واستخدامها

في هذه المهمة، ستقوم بإنشاء أنواع مختلفة من تعليقات التعليمات البرمجية وإزالتها.

1. في لوحة محرر Visual Studio Code، أدخل التعليمات البرمجية التالية:

   string firstName = "Bob";
   int widgetsSold = 7;
   Console.WriteLine($"{firstName} sold {widgetsSold} widgets.");
   

2. لتعديل التعليمات البرمجية الخاصة بك مع تعليقات التعليمات البرمجية والمراجعات، قم بتحديث التعليمات البرمجية الخاصة بك كما يلي:

   string firstName = "Bob";
   int widgetsPurchased = 7;
   // Testing a change to the message.
   // int widgetsSold = 7;
   // Console.WriteLine($"{firstName} sold {widgetsSold} widgets.");
   Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");
   

3. خذ دقيقة لمراجعة تعليقاتك وتحديثات التعليمات البرمجية.

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

4. في قائمة Visual Studio Code File ، انقر فوق Save.

5. في طريقة عرض EXPLORER، لفتح Terminal في موقع مجلد TestProject، انقر بزر الماوس الأيمن فوق TestProject، ثم حدد Open in Integrated Terminal.

6. في موجه الأوامر Terminal، اكتب dotnet run ثم اضغط على Enter.

   ينبغي أن تشاهد المخرج التالي:

   Bob purchased 7 widgets.
   

   مرة أخرى، إذا كنت راضيا عن التحديثات، فاحذف التعليمات البرمجية القديمة التي تم التعليق عليها.

7. حذف تعليقات التعليمات البرمجية.

   يجب أن تتطابق التعليمة البرمجية مع ما يلي:

   string firstName = "Bob";
   int widgetsPurchased = 7;
   Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");
   

8. لتطبيق تعليق كتلة يقوم بتعليق أسطر متعددة، قم بتحديث التعليمات البرمجية الخاصة بك كما يلي:

   /*
   string firstName = "Bob";
   int widgetsPurchased = 7;
   Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");
   */
   

   تعليقات الحظر رائعة إذا كنت بحاجة إلى كتابة تعليق طويل أو إزالة العديد من أسطر التعليمات البرمجية. حظر التعليقات استخدام /* في بداية التعليمات البرمجية وفي */ النهاية. استخدام تعليق كتلة هو أسرع وأسهل طريقة لتعطيل ثلاثة أسطر أو أكثر من التعليمات البرمجية.

9. استبدل التعليمات البرمجية الموجودة لديك بالآتي:

   Random random = new Random();
   string[] orderIDs = new string[5];
   // Loop through each blank orderID
   for (int i = 0; i < orderIDs.Length; i++)
   {
       // Get a random value that equates to ASCII letters A through E
       int prefixValue = random.Next(65, 70);
       // Convert the random value into a char, then a string
       string prefix = Convert.ToChar(prefixValue).ToString();
       // Create a random number, pad with zeroes
       string suffix = random.Next(1, 1000).ToString("000");
       // Combine the prefix and suffix together, then assign to current OrderID
       orderIDs[i] = prefix + suffix;
   }
   // Print out each orderID
   foreach (var orderID in orderIDs)
   {
       Console.WriteLine(orderID);
   }
   

   إشعار

   هناك العديد من مفاهيم «C#» في قائمة هذه التعليمة البرمجية قد تكون جديدة عليك. ليس من الضروري فهم ما تقوم به التعليمة البرمجية من أجل تقدير كيف يمكن أن تساعد التعليقات القراء على فهم الغرض من التعليمة البرمجية.

10. خذ دقيقة لمعرفة ما إذا كان يمكنك معرفة الغرض من التعليمات البرمجية.

    مع مراعاة التعليقات، قد تتمكن من معرفة ما تقوم به التعليمة البرمجية (بافتراض أن التعليقات تصف الحالة الحالية بدقة وتم تحديثها كما تم تحديث التعليمة البرمجية). ولكن هل يمكنك تخمين سبب وجود هذه التعليمة البرمجية؟ لن يكون من المفيد إذا كان هناك بعض التفسير في الجزء العلوي من ملف التعليمات البرمجية الذي قدم بعض السياق ووصف الغرض منه؟

11. فكر في كيفية تحسين التعليقات.

    لاحظ أن هناك مشكلتين رئيسيتين مع هذه التعليقات:

    • تفسر تعليقات التعليمة البرمجية بشكل غير ضروري الوظيفة الواضحة للخطوط الفردية للتعليمة البرمجية. تعتبر هذه التعليقات منخفضة الجودة؛ لأنها مجرد شرح لكيفية عمل «C#» أو أساليب مكتبة فئات «Microsoft .NET». إذا لم يكن القارئ على دراية بهذه الأفكار، فيمكنه البحث عنها باستخدام learn.microsoft.com أو IntelliSense.
    • لا توفر تعليقات التعليمة البرمجية أي سياق للمشكلة التي يتم حلها بواسطة التعليمة البرمجية. تعتبر هذه التعليقات منخفضة الجودة؛ لأن القارئ لا يحصل على أي نتيجة بخصوص الغرض من هذه التعليمة البرمجية، خاصةً فيما يتعلق بالنظام الأكبر.

12. إزالة التعليقات الموجودة.

    يجب أن تتطابق التعليمة البرمجية مع ما يلي:

    Random random = new Random();
    string[] orderIDs = new string[5];
    
    for (int i = 0; i < orderIDs.Length; i++)
    {
        int prefixValue = random.Next(65, 70);
        string prefix = Convert.ToChar(prefixValue).ToString();
        string suffix = random.Next(1, 1000).ToString("000");
    
        orderIDs[i] = prefix + suffix;
    }
    
    foreach (var orderID in orderIDs)
    {
        Console.WriteLine(orderID);
    }
    

    لاحظ أن التعليمات البرمجية أقل ازدحاما بالفعل.

13. لإضافة تعليق يشرح الغرض الأعلى مستوى من التعليمات البرمجية الخاصة بك، قم بتحديث التعليمات البرمجية الخاصة بك كما يلي:

    /*
      The following code creates five random OrderIDs
      to test the fraud detection process.  OrderIDs 
      consist of a letter from A to E, and a three
      digit number. Ex. A123.
    */
    Random random = new Random();
    string[] orderIDs = new string[5];
    
    for (int i = 0; i < orderIDs.Length; i++)
    {
        int prefixValue = random.Next(65, 70);
        string prefix = Convert.ToChar(prefixValue).ToString();
        string suffix = random.Next(1, 1000).ToString("000");
    
        orderIDs[i] = prefix + suffix;
    }
    
    foreach (var orderID in orderIDs)
    {
        Console.WriteLine(orderID);
    }
    

    فائدة التعليق ذاتية. في جميع المسائل المتعلقة بسهولة قراءة التعليمة البرمجية، يجب عليك استخدام أفضل حكم. قم بما تعتقد أنه الأفضل لتحسين وضوح التعليمة البرمجية الخاصة بك.

خلاصة

الفوائد الأساسية من هذا التمرين:

• استخدام تعليقات التعليمة البرمجية لترك ملحوظات ذات معنى لنفسك حول المشكلة التي تحلها التعليمة البرمجية الخاصة بك.
• لا تستخدم تعليقات التعليمة البرمجية التي تشرح كيفية عمل «C#» أو مكتبة فئات «Microsoft .NET».
• استخدام تعليقات التعليمة البرمجية عند تجربة الحلول البديلة مؤقتًا حتى تصبح جاهزًا لتثبيت حل التعليمة البرمجية الجديد، وعند هذه النقطة يمكنك حذف التعليمة البرمجية القديمة.
• لا تثق أبدًا في التعليقات. قد لا تعكس التعليقات الحالة الحالية للتعليمة البرمجية بعد العديد من التغييرات والتحديثات.