Duplikasi dokumentasi implementasi antarmuka / menimpa baik atau buruk?

Jadi kami memiliki antarmuka seperti itu

/// <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();
}

Baru-baru ini, kami memainkan cerita dokumentasi yang melibatkan pembuatan dan memastikan bahwa ada banyak dokumentasi XML seperti di atas. Ini menyebabkan banyak duplikasi dokumentasi. Contoh implementasi:

/// <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
  }
}

Seperti yang Anda lihat, dokumentasi metode adalah rip langsung dari antarmuka.

Pertanyaan besarnya adalah, apakah ini hal yang buruk? Naluri saya memberi tahu saya ya karena duplikasi, tetapi sekali lagi mungkin tidak?

Kami juga memiliki duplikasi dokumentasi serupa lainnya dengan overridefungsi dan virtualfungsi.

Apakah ini buruk dan harus dihindari, atau tidak? Apakah ini sama sekali berharga?

c# documentation xml documentation-generation

— Earlz
sumber

Jika Anda menggunakan Resharper, Anda dapat mengubah komentar hanya dalam implementasi dan kemudian memperbarui antarmuka dengan menggunakan "Tarik anggota".

— vortexwolf

Saya melakukan ini, tetapi mungkin karena saya tidak begitu pandai menggunakan alat eksternal dan lebih suka pergi menavigasi ke file header antarmuka untuk melihat apa yang bisa saya lakukan dengan jenis hal tertentu (ini untuk C dan C ++ yang terpisah gagasan header dari file sumber). Memang mendapatkan sedikit pengulangan tapi saya mencoba mencari peluang untuk menambahkan rincian lebih spesifik yang berkaitan dengan kelas beton menimpa metode, misalnya saya suka dan saya memiliki hal OCD pergi di mana saya merasa seperti saya menghilangkan sesuatu yang penting jika saya tidak lihat komentar untuk setiap fungsi dalam file header.

Saya benar-benar menggunakan komentar dan tag Doxygen tapi saya sebenarnya tidak terlalu banyak melihat dokumen dalam proses pengkodean. Saya lebih suka hanya menavigasi ke file header dan melihat apa yang bisa saya lakukan dengan sesuatu. Mungkin hanya kasus seekor anjing tua yang kesulitan mengambil kebiasaan dan alat baru.

Secara umum, saya hanya akan menambahkan dokumentasi baru untuk metode pelaksanaan jika ada sesuatu yang spesifik tentang yang pelaksanaannya bahwa kebutuhan untuk disebutkan.

Di javadoc Anda dapat menautkan ke metode lain, yang akan memungkinkan Anda untuk hanya membuat tautan dalam implementasi ke dokumentasi metode di antarmuka. Saya pikir ini adalah bagaimana seharusnya dilakukan di. Net (berdasarkan saya membaca dokumentasi online, bukan pengalaman saya sendiri):

/// <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
  }
}

Dokumentasi untuk <see/>elemen: http://msdn.microsoft.com/en-us/library/acd0tfbe.aspx

— FrustratedWithFormsDesigner
sumber

Bagaimana dengan mengesampingkan dokumen XML di kelas yang diwarisi? Katakanlah saya membuat sub-kelas dari Collection<T>dan ingin menimpa Countdokumen XML propertinya.

— Shimmy