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 override
fungsi dan virtual
fungsi.
Apakah ini buruk dan harus dihindari, atau tidak? Apakah ini sama sekali berharga?
Jawaban:
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):
Dokumentasi untuk
<see/>
elemen: http://msdn.microsoft.com/en-us/library/acd0tfbe.aspxsumber
Collection<T>
dan ingin menimpaCount
dokumen XML propertinya.