Tôi nên bao gồm những gì trong các nhận xét tài liệu XML?

Tôi đang cố gắng làm cho một điểm để ghi lại mã của mình tốt hơn, đặc biệt là khi nói đến các nhận xét XML về các thành viên của lớp, nhưng thường thì nó chỉ cảm thấy ngớ ngẩn.

Trong trường hợp xử lý sự kiện, quy ước đặt tên và tham số là chuẩn và rõ ràng:

/// <summary>
/// Handler for myCollection's CollectionChanged Event.
/// </summary>
/// <param name="sender">Event Sender</param>
/// <param name="e">Event Arguments</param>
private void myCollection_CollectionChanged(object sender, NotifyCollectionChangedEventArgs e)
{
    // actual code here...
}

Tôi cũng thường xuyên có các thuộc tính đơn giản được đặt tên rõ ràng (IMO) để tóm tắt là dự phòng:

/// <summary>
/// Indicates if an item is selected.
/// </summary>
public bool ItemIsSelected
{ get { return (SelectedItem != null); } }

Tôi không cảm thấy như những bình luận như vậy không thêm bất kỳ thông tin nào mà bản tuyên bố không truyền đạt được. Sự khôn ngoan chung dường như là một nhận xét lặp lại mã tốt nhất là không được ghi lại.

Rõ ràng, tài liệu XML không chỉ là các nhận xét mã nội tuyến thông thường và lý tưởng sẽ có phạm vi bảo hiểm 100%. Tôi nên viết gì trong những trường hợp như vậy? Nếu những ví dụ này là OK, họ thêm giá trị nào mà tôi có thể không đánh giá cao bây giờ?

Nhận xét tài liệu XML được dành cho các thành viên công cộng.

Các trình biên dịch cảnh báo rõ ràng khẳng định điều này:

Thiếu nhận xét XML cho loại hoặc thành viên hiển thị công khai 'Type_or_Member'

Bạn chỉ nên thêm nhận xét XML cho các thành viên riêng nếu các thành viên đó chưa rõ ràng từ tên của họ.

Ý kiến ​​thuần túy ở đây, vì vậy hãy xem nó cho những gì nó có giá trị.

Tôi ghét những bình luận xml thừa. Chắc chắn là như vậy đối với những kiểu ma doc chỉ cần thêm khoảng trắng vào tên phương thức / thuộc tính. Nó không thêm giá trị và chỉ đơn giản làm mờ quan điểm của tôi về mã thực tế.

Nếu một cái gì đó cần làm rõ, bằng mọi cách, bình luận nó. Tuy nhiên, rất nhiều sự rõ ràng có thể được truyền đạt bằng các phương pháp tập trung nhỏ với các tên có ý nghĩa. Đừng bình luận mã nếu bạn có thể cải thiện nó và làm cho bình luận không cần thiết.

Đừng để tôi bắt đầu sử dụng this.và Me..

Là một lưu ý phụ, tôi rất thích có một addin Visual Studio cho phép tôi thay đổi mức độ hiển thị của các bình luận xml. (gợi ý)

Trên một tài liệu XML thành viên công khai phải khá dài dòng và đầy đủ, như @SLaks đã đề cập.

Tuy nhiên, chúng có thể thực sự hữu ích đối với các thành viên riêng tư, được bảo vệ hoặc nội bộ vì Visual Studio sẽ tạo ra các thông báo trực quan và trợ giúp các công cụ với các nhận xét tài liệu XML.

Điều này có nghĩa rằng:

// describe what this does
private void DoSomething() 
{
    // or describe it here...

Có thể là tài liệu hoàn toàn đủ, nhưng:

/// <summary>describe what this does</summary>
private void DoSomething() 
{

Sẽ dễ dàng hơn nhiều để xem nhanh từ nơi khác trong mã của bạn.

Nói chung về các nhận xét XML công khai Tôi đang viết cho một số người dùng API bên ngoài và về các nhận xét XML nội bộ tôi đang viết cho tôi hoặc những người khác trong nhóm của tôi.

Bỏ qua các mô tả tham số có lẽ là một ý tưởng tồi cho cái trước và tốt cho cái sau.

Tôi sẽ thêm (đặc biệt là trong các tài liệu API công khai) luôn bao gồm liệu gethoặc settrên các thuộc tính:

/// <summary>Gets a value indicating whether an item is selected.</summary>
public bool ItemIsSelected
{ 
    get { return SelectedItem != null; } 
}

Không rõ ràng từ intellisense của C # dù có gethay setkhông, nhưng đưa nó vào nhận xét XML sẽ có nghĩa là bạn có thể biết trong nháy mắt từ chú giải công cụ.