Sao chép tài liệu về triển khai / ghi đè giao diện tốt hay xấu?

Vì vậy, chúng tôi có một giao diện như vậy

/// <summary>
/// Interface for classes capable of creating foos
/// </summary>
public interface ICreatesFoo
{
  /// <summary>
  /// Creates foos
  /// </summary>
  void Create(Foo foo);
  /// <summary>
  /// Does Bar stuff
  /// </summary>
  void Bar();
}

Gần đây, chúng tôi đã chơi một câu chuyện tài liệu liên quan đến việc tạo và đảm bảo rằng có nhiều tài liệu XML như trên. Điều này gây ra rất nhiều sự trùng lặp của tài liệu mặc dù. Ví dụ thực hiện:

/// <summary>
/// A Foo Creator which is fast
/// </summary>
public class FastFooCreator : ICreatesFoo
{
  /// <summary>
  /// Creates foos
  /// </summary>
  public void Create(Foo foo)
  {
    //insert code here
  }
  /// <summary>
  /// Does Bar stuff
  /// </summary>
  public void Bar()
  {
    //code here
  }
}

Như bạn có thể thấy tài liệu phương thức là một rip thẳng từ giao diện.

Câu hỏi lớn là, đây có phải là một điều xấu? Ruột của tôi nói với tôi là có vì trùng lặp, nhưng sau đó có thể không?

Ngoài ra, chúng tôi có sao chép tài liệu tương tự khác với overridechức năng và virtualchức năng.

Đây có phải là xấu và nên tránh, hay không? Nó có đáng giá không?

c# documentation xml documentation-generation

— Bá tước
nguồn

Nếu bạn sử dụng Resharper, bạn chỉ có thể thay đổi nhận xét trong quá trình triển khai và sau đó cập nhật giao diện bằng cách sử dụng "Kéo thành viên lên".

— xoáy

Tôi làm điều này nhưng có lẽ vì tôi không giỏi sử dụng các công cụ bên ngoài và chỉ muốn điều hướng đến tệp tiêu đề của giao diện để xem tôi có thể làm gì với một loại điều cụ thể (điều này dành cho C và C ++ tách biệt khái niệm tiêu đề từ tập tin nguồn). Nó có một chút lặp đi lặp lại nhưng tôi cố gắng tìm cơ hội để thêm các chi tiết cụ thể hơn liên quan đến lớp cụ thể ghi đè các phương thức, ví dụ tôi thích nó và tôi có một điều OCD mà tôi cảm thấy như đã bỏ qua một điều quan trọng nếu tôi không xem bình luận cho mọi chức năng trong một tệp tiêu đề.

Tôi thực sự sử dụng các nhận xét và thẻ Doxygen nhưng tôi thực sự không nhìn vào các tài liệu quá nhiều trong quá trình mã hóa. Tôi thích chỉ điều hướng đến tệp tiêu đề và xem những gì tôi có thể làm với một cái gì đó. Có thể chỉ là một trường hợp của một con chó già gặp khó khăn trong việc chọn thói quen và công cụ mới.

Nói chung, tôi chỉ thêm tài liệu mới vào các phương thức triển khai nếu có điều gì đó cụ thể về việc triển khai đó cần được đề cập.

Trong javadoc, bạn có thể liên kết với các phương thức khác, điều này sẽ cho phép bạn chỉ cần tạo một liên kết trong quá trình thực hiện với tài liệu phương thức trong giao diện. Tôi nghĩ rằng đây là cách nó được thực hiện trong .Net (dựa trên việc tôi đọc tài liệu trực tuyến, không phải kinh nghiệm của riêng tôi):

/// <summary>
/// Interface for classes capable of creating foos
/// </summary>
public interface ICreatesFoo
{
  /// <summary>
  /// Creates foos
  /// </summary>
  void Create(Foo foo);
  /// <summary>
  /// Does Bar stuff
  /// </summary>
  void Bar();
}

/// <summary>
/// A Foo Creator which is fast
/// </summary>
public class FastFooCreator : ICreatesFoo
{
  /// <summary>
  /// <see cref="ICreatesFoo.Create(Foo)"/>
  /// </summary>
  public void Create(Foo foo)
  {
    //insert code here
  }
  /// <summary>
  /// <see cref="ICreatesFoo.Bar()"/>
  /// Also Note: Implementation of Bar() in FastFooCreator
  /// requires a minimum of 512 MB RAM to Bar the Foo. 
  /// </summary>
  public void Bar()
  {
    //code here
  }
}

Tài liệu cho <see/>phần tử: http://msdn.microsoft.com/en-us/l Library / acd0tfbe.aspx

— Thất vọngWithFormsDesigner
nguồn

Làm thế nào về việc ghi đè các tài liệu XML trong một lớp được kế thừa? Giả sử tôi tạo một lớp con Collection<T>và muốn ghi đè các Counttài liệu XML thuộc tính của nó .

— Shimmy