Trong công ty của chúng tôi, chúng tôi viết các bình luận Xml quá mức. Một phương pháp điển hình là đã được ghi nhận như sau:C# XML Nhận xét: Có bao nhiêu tài liệu tham khảo trong các nhận xét XML hữu ích?
/// <summary>
/// Determines whether this <see cref="IScheduler"/> contains a specific <see cref="ISchedule"/>.
/// </summary>
/// <param name="schedule">The <see cref="ISchedule"/> to locate in this <see cref="IScheduler"/>.</param>
/// <returns>
/// Returns <see langword="true"/> if <paramref name="schedule"/> is found in this <see cref="IScheduler"/>; otherwise, <see langword="false"/>.
/// </returns>
bool Contains(ISchedule schedule);
/// <summary>
/// Removes and <see cref="IDisposable.Dispose"/>s the first occurrence of a specific <see cref="ISchedule"/>
/// from this <see cref="IScheduler"/>.
/// </summary>
/// <param name="schedule">The <see cref="ISchedule"/> to remove from this <see cref="IScheduler"/>.</param>
/// <exception cref="System.ArgumentNullException">Is thrown when the parameter schedule is null.</exception>
/// <exception cref="System.ArgumentException">Is thrown when the <see cref="ISchedule"/> is not found in this <see cref="IScheduler"/> or was of the wrong type.</exception>
void Remove(ISchedule schedule);
Như bạn có thể thấy hầu hết các danh từ có thể được tham chiếu sử dụng một thẻ <see cref>.
Tôi thấy điều này quá nhiều. Hầu hết các tệp mã của chúng tôi đều bị thổi phồng với các nhận xét như vậy. Làm cho phần nhận xét gần như không đọc được.
Bạn nghĩ sao? Bạn có thích loại tài liệu này trong mã hay không?
Như thường lệ, tôi nghĩ rằng không có câu trả lời đen/trắng cho một loại câu hỏi như vậy, đó là lý do tại sao tôi làm cho nó wiki.
CHỈNH SỬA:
Câu hỏi của tôi không phải là nếu chính thẻ tự xem hữu ích theo mặc định. Rõ ràng là các liên kết được tạo ra trong tệp .chm (hoặc bất kỳ loại tài liệu được tạo nào khác) rất hữu ích. Câu hỏi của tôi là nếu nó thực sự hữu ích để gắn thẻ mọi sự xuất hiện của mọi danh từ "có thể liên kết" trong các nhận xét.
Chúng tôi sử dụng Sandcastle để tạo tài liệu mỗi tối. Thật không may nó là rất hiếm được sử dụng bởi các nhà phát triển khác, nhưng đó là một vấn đề khác.
Nó cũng rất hữu ích khi sử dụng tính năng "Tài liệu nhanh" của ReSharper (Ctrl-Q trong ánh xạ chính của tôi). – adrianbanks