แบบฝึกหัด - สร้างข้อคิดเห็นของโค้ดที่มีประสิทธิภาพ

เสร็จสมบูรณ์เมื่อ

ในแบบฝึกหัดนี้ คุณจะเพิ่มบันทึกย่อในโค้ดของคุณและปิดใช้งานบางบรรทัดของโค้ดชั่วคราวจากการคอมไพล์ จากนั้นคุณจะได้ดูว่าคอมไพเลอร์ C# เข้าใจช่องว่างและวิธีใช้ช่องว่างได้อย่างไร เพื่อเพิ่มความยากง่ายในการอ่านโค้ดของคุณ

ข้อคิดเห็นเกี่ยวกับรหัสคืออะไร

คอมไพเลอร์คอมไพเลอร์ละเว้นทุกอย่างหลังจากสัญลักษณ์ความคิดเห็นรหัสในบรรทัดปัจจุบัน

// This is a code comment!

ซึ่งอาจดูไม่มีประโยชน์ในตอนแรก อย่างไรก็ตามมีประโยชน์ในสามสถานการณ์:

• เมื่อคุณต้องการออกจากบันทึกเกี่ยวกับเจตนาของการส่งผ่านรหัส จะเป็นประโยชน์มากในการรวมความคิดเห็นโค้ดที่อธิบายวัตถุประสงค์หรือกระบวนการคิดเมื่อคุณเขียนชุดคําแนะนําการเขียนโค้ดที่ท้าทายเป็นพิเศษ ตนเองในอนาคตของคุณจะขอบคุณ
• เมื่อคุณต้องการลบโค้ดชั่วคราวออกจากแอปพลิเคชันของคุณ เพื่อลองใช้วิธีการอื่น แต่คุณยังไม่ได้ทําให้แนวคิดใหม่ของคุณสามารถใช้งานได้ คุณสามารถแสดงความคิดเห็นรหัสเขียนรหัสใหม่และเมื่อคุณโน้มน้าวใจรหัสใหม่จะทํางานในแบบที่คุณต้องการคุณสามารถลบเก่าได้อย่างปลอดภัย (รหัสที่แสดงความคิดเห็น)
• เพิ่มข้อความเช่น TODO การเตือนคุณเพื่อดูทางเดินที่กําหนดของรหัสในภายหลัง แม้ว่าคุณควรใช้สิ่งนี้อย่างพิพากษาแต่ก็เป็นวิธีที่มีประโยชน์ คุณอาจกําลังทํางานกับคุณลักษณะอื่นเมื่อคุณอ่านบรรทัดของโค้ดที่จุดประกายความกังวล แทนที่จะละเว้นความกังวลใหม่ คุณสามารถทําเครื่องหมายสําหรับการตรวจสอบในภายหลัง

หมายเหตุ

ควรใช้ข้อคิดเห็นเกี่ยวกับรหัสเพื่อระบุว่าโค้ดไม่สามารถทําอะไรได้ บ่อยครั้งที่นักพัฒนาอัปเดตรหัสของพวกเขา แต่ลืมที่จะอัปเดตความคิดเห็นรหัส เป็นการดีที่สุดที่จะใช้ข้อคิดเห็นสําหรับแนวคิดระดับสูงกว่าและไม่เพิ่มข้อคิดเห็นเกี่ยวกับวิธีการทํางานของแต่ละบรรทัดของโค้ด

เตรียมสภาพแวดล้อมการเข้ารหัสของคุณ

โมดูลนี้ประกอบด้วยแบบฝึกหัดที่แนะนําคุณเกี่ยวกับกระบวนการสร้างและการเรียกใช้โค้ดตัวอย่าง คุณควรทํากิจกรรมเหล่านี้ให้เสร็จสมบูรณ์โดยใช้ Visual Studio Code เป็นสภาพแวดล้อมการพัฒนาของคุณ การใช้ Visual Studio Code สําหรับกิจกรรมเหล่านี้จะช่วยให้คุณเขียนและเรียกใช้โค้ดในสภาพแวดล้อมของนักพัฒนาที่มืออาชีพใช้ทั่วโลกได้อย่างสะดวกขึ้น

1. เปิด Visual Studio Code

   คุณสามารถใช้เมนูเริ่มต้นของ Windows (หรือทรัพยากรที่เทียบเท่าสําหรับระบบปฏิบัติการอื่น) เพื่อเปิด Visual Studio Code

2. บนเมนู ไฟล์ รหัส Visual Studio เลือก เปิดโฟลเดอร์

3. ในกล่องโต้ตอบ เปิดโฟลเดอร์ ให้ไปยังโฟลเดอร์ Windows Desktop

   หากคุณมีตําแหน่งโฟลเดอร์อื่นที่คุณเก็บโครงการโค้ดไว้ คุณสามารถใช้ตําแหน่งโฟลเดอร์นั้นแทนได้ สําหรับการฝึกนี้ สิ่งสําคัญคือการมีตําแหน่งที่ตั้งที่ง่ายต่อการค้นหาและจดจํา

4. ในกล่องโต้ตอบ เปิด โฟลเดอร์ ให้เลือก เลือกโฟลเดอร์

   ถ้าคุณเห็นกล่องโต้ตอบความปลอดภัยที่ถามว่าคุณเชื่อถือผู้เขียนหรือไม่ ให้เลือก ใช่

5. บนเมนู เทอร์มินัล Visual Studio Code ให้เลือก เทอร์มินัลใหม่

   โปรดสังเกตว่าพร้อมท์คําสั่งในแผงเทอร์มินัล จะแสดงเส้นทางโฟลเดอร์สําหรับโฟลเดอร์ปัจจุบัน เช่น:

   C:\Users\someuser\Desktop>
   

   หมายเหตุ

   ถ้าคุณกําลังทํางานบนพีซีของคุณเองแทนที่จะเป็น Sandbox หรือสภาพแวดล้อมที่เป็นโฮสต์ และคุณจบมอดูล Microsoft Learn อื่นๆ ใน C# ซีรี่ส์นี้ คุณอาจสร้างโฟลเดอร์โครงการสําหรับตัวอย่างโค้ดไว้แล้ว ถ้าเป็นกรณีนี้ คุณสามารถข้ามขั้นตอนถัดไป ซึ่งใช้เพื่อสร้างแอปคอนโซลในโฟลเดอร์ TestProject

6. ที่พรอมต์คําสั่งเทอร์มินัล หากต้องการสร้างแอปพลิเคชันคอนโซลใหม่ในโฟลเดอร์ที่ระบุ ให้ป้อนพร้อมท์ต่อไปนี้:

   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 เลือก เปิดโฟลเดอร์

9. ในกล่องโต้ตอบ เปิดโฟลเดอร์ เลือกโฟลเดอร์ CsharpProjects จากนั้นเลือก เลือกโฟลเดอร์

10. ในมุมมอง EXPLORER ให้ขยายโฟลเดอร์ TestProject จากนั้นเลือก Program.cs

11. ลบบรรทัดรหัสที่มีอยู่

    คุณจะใช้โครงการคอนโซล C# นี้เพื่อสร้าง สร้าง และเรียกใช้ตัวอย่างโค้ดในระหว่างโมดูลนี้

12. ปิดแผงเทอร์มินัล

สร้างและใช้ข้อคิดเห็นเกี่ยวกับรหัส

ในงานนี้ คุณจะสร้างและลบข้อคิดเห็นเกี่ยวกับรหัสชนิดต่างๆ

1. ในแผงตัวแก้ไขรหัส Visual Studio ให้ป้อนโค้ดต่อไปนี้:

   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 ให้คลิก บันทึก

5. ในมุมมอง EXPLORER เมื่อต้องการเปิดเทอร์มินัลที่ตําแหน่งที่ตั้งโฟลเดอร์ TestProject ของคุณ ให้คลิกขวาที่ TestProject จากนั้นเลือกเปิดในเทอร์มินัลรวม

6. ที่พร้อมท์คําสั่งเทอร์มินัล ให้พิมพ์ 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. พิจารณาวิธีที่คุณจะปรับปรุงข้อคิดเห็น

    โปรดสังเกตว่ามีปัญหาหลักสองประการเกี่ยวกับข้อคิดเห็นเหล่านี้:

    • ความคิดเห็นรหัสไม่จําเป็นอธิบายฟังก์ชันการทํางานที่ชัดเจนของแต่ละบรรทัดของรหัส ซึ่งถือว่าเป็นข้อคิดเห็นที่มีคุณภาพต่ําเนื่องจากพวกเขาแค่อธิบายวิธีการทํางานของไลบรารีคลาส .NET# หรือ C# เท่านั้น หากผู้อ่านไม่คุ้นเคยกับแนวคิดเหล่านี้ พวกเขาสามารถค้นหาแนวคิดเหล่านี้ได้โดยใช้ 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# หรือ .NET
• ใช้ข้อคิดเห็นโค้ดเมื่อพยายามแก้ไขปัญหาชั่วคราวจนกว่าคุณจะพร้อมที่จะส่งไปยังโซลูชันโค้ดใหม่ ซึ่งจุดนั้นคุณสามารถลบโค้ดเก่าได้
• ไม่เชื่อถือข้อคิดเห็น ซึ่งอาจไม่แสดงสถานะปัจจุบันของโค้ดหลังจากการเปลี่ยนแปลงและการอัปเดตจํานวนมาก