Code Comments

เวลาเราเขียนโค้ด บางครั้งเราจะแทนด้วยตัวอักษรหรือสั้น ซึ่งจริงๆแล้ว มีความหมายมากกว่านั้นแต่เราเขียนยาวๆไม่ได้ เราจะเห็น keywords ของ C# มากมาย เช่น class, namespace, หรือ public compiler จะเช็คตลอดเวลาว่าเราใช้ keyword เหล่านี้, ตัวแปร, หรือ method ถูกต้องหรือไม่ แต่เราก็มี feature อยู่อย่างนึงทีทำให้เราเขียนอะไรก็ได้บนโค้ด นั่นก็คือ code comments

คงเคยเห็น comment กันมาบ้างในการเขียนโค้ดภาษาอื่นๆ แนวคิดของ comment ก็จะเหมือนๆกัน ลองมาดูว่า C# สามารถเขียน comment แบบไหนได้บ้าง

Single-line comment (comment แบบบันทัดเดียว)

Comment พื้นฐานก็คือการเขียนแบบบันทัดเดียว เราจะมาดูตัวอย่างกัน

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

เขียนขึ้นต้นด้วย two forward slash (//) แล้วตามด้วยข้อความที่เราอยากจะเขียน compiler จะไม่ประมวลผล ถ้าจะขึ้นบันทัดใหม่ ก็เขียน // เพิ่ม

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

Multi-line comments (comment แบบหลายบันทัด)

ถ้าจะ comment หลายๆบรรทัด เราก็จะใส่ start stop character ดังนี้

/*  
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  
{
    ......

โดยการใช้ start sequence of forward-slash-asterisk (/*) แล้วตามด้วยข้อความที่เราอยากจะเขียน จบด้วย end sequence of asterisk-forward-slash (*/)

ซึ่งการใช้แบบบรรทัดเดียวหรือแบบหลายบรรทัดก็ขึ้นอยู่กับความชอบของแต่ละบุคคล

Documentation comments (comment แบบเอกสาร)

Documentation comment (comment แบบเอกสาร) หรือ XML Documentation comment ลักษณะเหมือน comment ทั่วไป แต่ จะมีทั้ง แบบบันทัดเดียวแต่ 3 slash (///) และ แบบหลายบันทัดแต่เพิ่มที่ asterisk ตอนเริ่มต้น

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; }
}

นี่คือการใช้งานแบบ documentation comment ทีใช้กันอย่างกว้างขวาง

การเขียนชนิดของสมาชิกใน documentation comment นั้นจะกล่าวในบทต่อๆไป

Code comments & the Task list (comment แบบรายชื่องาน)

ถ้าใช้ Visual Studio เราจะมีตัวช่วยใน Task List Window ซึ่งเรียกใช้ได้จาก menu View > Task List

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

ถ้า comment แบบบันทัดเดียว ขึ้นต้นด้วย TODO หรือ HACK มันจะไปขึ้นที่ Task List ของ Visual Studio ดังนี้

และยังมีอีกหลายชนิด ขึ้นอยู่กับ version ของ Visual Studio ที่ใช้ เช่น

• TODO (ต้องทำ)
• HACK (ไม่ได้เอามาใช้จริง)
• NOTE (ข้อความ)
• UNDONE (ยังทำไม่เสร็จ)

เรายังสามารถเพิ่ม token ของเราเองได้ด้วย วิธีทำดังนี้ this article

สรุป

Code comment มีประโยชน์อย่างมากที่จะช่วยให้เราหรือเพื่อนร่วมงานเข้าใจและทำงานต่อได้ หรือเราอยากจะทดสอบโค้ดของเรา เราก็ทำได้อย่างรวดเร็ว ถ้าทดสอบผ่าน เราก็ลบโค้ดเก่า ถ้าไม่ผ่านเราก็ใช้โค้ดเก่าที่เราใส่ comment ไว้และลบโค้ดใหม่

Comment จะไม่ไปรวมอยู่ใน DLL หรือ EXE end-user จะไม่มีทางเห็น และเราสามารถเขียน comment ที่ไหนก็ได้