Một nhận xét phương pháp có nên bao gồm cả mô tả tóm tắt và trả về khi chúng thường giống nhau không?

Tôi là người đề xuất mã tài liệu đúng và tôi nhận thức rõ những nhược điểm có thể có của nó . Đó là ngoài phạm vi của câu hỏi này.

Tôi thích tuân theo quy tắc thêm nhận xét XML cho mọi thành viên công cộng, xem xét mức độ tôi thích IntelliSense trong Visual Studio.

Tuy nhiên, có một dạng dư thừa, mà ngay cả một người bình luận quá mức như tôi cũng bị làm phiền. Như một ví dụ lấy List.Exists () .

/// <summary>
///     Determines whether the List<T> contains elements
///     that match the conditions defined by the specified predicate.
/// </summary>
/// <returns>
///     true if the List<T> contains one or more elements that match the
///     conditions defined by the specified predicate; otherwise, false.
/// </returns>
public bool Exists( Predicate<T> match )
{
    ...
}

Summaryvà returnsvề cơ bản là nói điều tương tự. Tôi thường kết thúc việc viết tóm tắt nhiều hơn từ returnsgóc độ, bỏ returnshoàn toàn tài liệu.

Trả về true khi Danh sách chứa các phần tử khớp với các điều kiện được xác định bởi vị từ đã chỉ định, sai khác.

Ngoài ra, tài liệu trả về không hiển thị trong IntelliSense, vì vậy tôi thay vì viết bất kỳ thông tin liên quan nào ngay lập tức vào summary.

1. Tại sao bạn cần phải làm tài liệu returnsriêng biệt từ summary?
2. Bất kỳ thông tin về lý do tại sao Microsoft áp dụng tiêu chuẩn này?

Bạn có thể suy ra cái này từ cái khác, nhưng hai phần đó vẫn tách biệt, vì nó giúp tập trung vào phần mà người đó quan tâm khi xem xét / sử dụng mã .

Lấy ví dụ của bạn, tôi muốn viết:

/// <summary>
/// Determines whether the List<T> contains elements that match the conditions
/// defined by the specified predicate.
/// </summary>
/// <returns>
/// A value indicating whether at least one element matched the predicate.
/// </returns>
public bool Exists(Predicate<T> match)
{
    ...
}

• Nếu tôi đang xem lại mã này và tôi muốn biết phương thức này làm gì, tôi đã đọc tóm tắt và đó là tất cả những gì tôi quan tâm.

• Bây giờ, hãy tưởng tượng tôi đang sử dụng phương pháp của bạn và giá trị trả về tôi nhận được là lạ, được đưa vào đầu vào. Bây giờ, tôi không thực sự muốn biết phương thức này làm gì, nhưng tôi muốn biết thêm về giá trị trả về. Ở đây, <returns/>phần giúp đỡ, và tôi không cần phải đọc tóm tắt.

Một lần nữa, trong ví dụ này, bạn có thể suy ra tóm tắt từ <returns/>và suy ra giá trị trả về dự kiến ​​từ tóm tắt. Nhưng đưa cùng một đối số đến mức cực đoan, không cần phải ghi lại phương thức của bạn trong trường hợp này: tên của phương thức, được đặt bên trong List<T>, với Predicate<T> matchtư cách là một đối số duy nhất khá rõ ràng.

Hãy nhớ rằng, mã nguồn được viết một lần nhưng đọc nhiều lần . Nếu bạn có thể giảm tiêu thụ đặc biệt cho những người đọc thêm mã của bạn, trong khi dành mười giây để viết một câu bổ sung trong tài liệu XML, hãy làm điều đó.

Cách sử dụng của tôi:
<summary>mô tả những gì phương thức làm (để có được <returns>).
<returns>mô tả giá trị trả về .

Liên kết đến MSDN : <summary>.<returns>

Tại sao bạn cần phải trả lại tài liệu riêng biệt từ tóm tắt?

Tôi nghĩ rằng nếu phần tóm tắt thực sự dài và mô tả, có thể hữu ích khi có một phần trả về ngắn gọn, riêng biệt ở cuối.

Tôi thường chỉ viết <summary>phần trong mã của riêng tôi, diễn đạt theo cách bạn đã nói "Trả về _ ".

Tôi đưa ra bất kỳ nhận xét nào mà người gọi nên biết rằng không rõ ràng từ tên phương thức và tham số (và tên của họ). Hy vọng rằng mặc dù, tên phương thức và tham số làm cho nó đủ rõ ràng để nhận xét có thể rất ngắn gọn.

Gần đây tôi đã bị xâu xé bởi cùng một câu hỏi triết học và tôi vẫn không chắc giải pháp tốt là gì. Nhưng cho đến nay, đây là cách tiếp cận của tôi ...

• Tài liệu phương pháp chỉ mô tả những gì người gọi bên ngoài cần biết. Nó không nói về cách thức công việc này được thực hiện trong nội bộ, nhưng đề cập đến a) tại sao người gọi muốn gọi phương thức này, b) kết quả mong đợi của việc gọi phương thức là gì. Nếu có nhu cầu ghi lại cách thức hoạt động của phương thức, tôi sẽ đặt nó vào thân mã.
• Nếu một phương thức có đủ độ phức tạp với nó, thì mô tả chung và phần [trả về] riêng biệt dường như là hợp lý. Bạn không muốn người đọc đọc toàn bộ mô tả và cố gắng suy luận cách diễn giải giá trị trả về.
• Nếu phương thức này đơn giản đến mức cách tốt nhất để mô tả những gì nó làm là nói điều gì đó như "Phương thức này trả về địa chỉ của người đó", thì tôi bỏ qua phần [trả về] vì việc thêm dường như đi ngược lại nguyên tắc DRY và tôi một người ủng hộ rất lớn về điều đó. Rất nhiều phương pháp truy cập một lớp lót dường như rơi vào thể loại này.

Tóm tắt nên được mô tả như có thể hữu ích; các mô tả của các tham số và giá trị trả về nên ngắn gọn và ngọt ngào. Nếu bạn có lựa chọn giữa một từ và năm, hãy sử dụng một từ. Hãy thắt chặt ví dụ của bạn:

đúng nếu Danh sách chứa một hoặc nhiều phần tử khớp với các điều kiện được xác định bởi vị từ đã chỉ định; mặt khác, sai

trở thành

đúng nếu bất kỳ yếu tố nào của Danh sách khớp với vị ngữ; nếu không thì sai.