Tạo Comment và Documentation trong C#

A. Các kiểu chú thích

Bạn đã biết trong mỗi file code, tất các mã phải tuân thủ theo quy tắc cú pháp của ngôn ngữ đó. Việc gõ sai cấu trúc sẽ đem lại vô số lỗi không đáng có. Hơn nữa ngoài việc viết mã trong sáng, sạch sẽ bạn cũng cần đưa ra chú thích rõ ràng ở một số điểm đáng chú ý. Hay đơn giản bạn muốn người nào đó đọc và hiểu bạn đang làm gì, thì hầu hết các ngôn ngữ lập trình đều hộ trợ chú thích bên trong code. Điều đó không ảnh hưởng tới code của bạn, trình biên dịch sẽ bỏ qua nó . . .

Trong C# có ba kiểu hay được sử dụng và dù là kiểu nào thì chúng đều có dạng màu xanh như nhau.

Comment chỉ trên một dòng

Syntax:

// Comment here: Bắt đầu với hai dấu '/' và chỉ có tác dụng trên một dòng

Comment trên nhiều dòng

Syntax:

/*
  Cặp dấu '/*'  '*/'  tác dụng mở và đóng một đoạn chú thích trên nhiều dòng
*/

Hai kiểu trên có thể dùng mọi nơi trong mã nguồn của bạn.

Documentation cho phương thức và lớp

Loại này có đôi chút khác biệt, nó bắt đầu với 3 dấu '/' và nó thường được sử dụng để ghi chú, giải nghĩa cho một phương thức hoặc lớp.

Syntax:

Sau khi bạn viết một phương thức hoặc lớp, đặt con trỏ chuột lên trước một dòng và gõ '///' 3 lần VS Studio sẽ tự generate ra cho bạn.

Có một điều: '/**' '*/' trong hình trên hoàn toàn là kiểu chú thích nhiều dòng nhưng bạn có thể dùng thay thế kiểu tài liệu nếu muốn. Bằng việc thêm các thẻ Tag có sẵn để nó được mạch lạc hơn.

Trong C# có hỗ trợ thêm các thẻ tag sau:

/// 
/// <![CDATA[]]>
/// <c></c>
/// <code></code>
/// <example></example>
/// <exception cref=""></exception>
/// <include file='' path='[@name=""]'/>
/// <list type=""></list>
/// <para></para>
/// <param name=""></param>
/// <paramref name=""/>
/// <permission cref=""></permission>
/// <remarks></remarks>
/// <returns></returns>
/// <see cref=""/>
/// <seealso cref=""/>
/// <summary></summary>
/// <typeparam name=""></typeparam>
/// <typeparamref name=""/>
/// <value></value>
/// <YourTag></YourTag>

Những thẻ này phải nằm sau 3 dấu '/' một số thẻ được VS tự động generate ra khi bạn tạo doccument còn lại bạn phải tự thêm vào và một số chỉ tồn tại bằng cách lồng vào các thẻ khác, chúng bổ trợ cho nhau. Bạn có thể xem chi tiết tại thư viện MSDN của Microsoft

Loại này như một gợi ý giải thích cho đoạn chú thích của bạn rõ ràng chứ không có tác dụng như mã code. Thì bạn có thể hiểu cái tên của nó đồng nghĩa nội dụng bạn ghi trong đó là gì, và các thẻ Tag này được hỗ trợ trên Docummentation như hình trên. Nếu bạn sử dụng trên Documentation thẻ tag cần phải có thẻ đóng và mở, và tên của thẻ phải trùng nhau như demo ở trên. Bạn ghi thẻ tag ở kiểu chú thích nhiều dòng hoặc một dòng cũng được không sao nhưng thẻ tag đó cũng chỉ là ghi chú bình thường kiểu thủ công, Visual không hỗ trợ !

B. Sử dụng chú thích

Kiểu chú thích trên một hoặc nhiều dòng, có thể được dùng khắp mã nguồn. Kiểu chú thích documentation thì thường được dùng để mô tả đặc tính của class, phương thức.

Và thông thường khi gõ '///' trên mỗi phương thức và class Visula studio tự generate cho bạn đầy đủ documment, bạn có thể thêm thẻ tag để bổ sung mô tả.

Trong quá trình code đôi khi ta cần vô hiệu hóa một khoản code ngắn hay dài, cách đơn giản và nhanh nhất là chuyển về dạng chú thích. Bằng cách bôi đen đoạn code của bạn và nhấn tổ hợp phím Ctrl + K + C Và để hoàn lại thao tác này ta lại nhấn Ctrl + K + U.

Trong Visual Studio nếu bạn trỏ chuột lên phương thức hay class nào được tham chiếu thì sẽ thấy liệu hướng dẫn của nó. Hoặc đối với class do bạn khởi tạo, nếu bạn sử dụng một tài liệu chú thích thì nó sẽ được show lên như thế này: