it-swarm.dev

Arayüz, uygulama veya her ikisini de yorumlayınız.

Arayüzlerimize hepimizin (rahatsız edilebildiğimizde!) Yorum yaptığını hayal ediyorum. Örneğin.

/// <summary>
/// Foo Interface
/// </summary>
public interface Foo
{
    /// <summary>
    /// Will 'bar'
    /// </summary>
    /// <param name="wibble">Wibble factor</param>
    void Bar(string wibble);
}

Uygulamayı da yorumluyor musunuz (örneğin bir kütüphanenin parçası olarak müşterilere de sağlanabilir)? Eğer öyleyse, ikisini senkronize etmeyi nasıl başarabilirsin? Yoksa sadece 'Dokümantasyon için arayüzü görün' yorumunu ekliyor musunuz?

Teşekkürler

108
ng5000

Genel bir kural olarak, kodla aynı DRY (Kendinizi Tekrar Etmeyin) ilkesini kullanıyorum:

  • arayüzde arayüzü belgeleyin
  • uygulamada, uygulamanın özelliklerini belgeleyin

Java özel: Uygulamayı belgelerken, arabirimden javadocs "dahil etmek" için {@inheritDoc} etiketini kullanın.

Daha fazla bilgi için:

87
Neeme Praks

GhostDoc addin kullanıyorsanız, sağ tıklayıp yöntemde "Bu Belge" yi seçtiğinizde uygulamayı arayüzden gelen yorumlarla günceller.

7
NikolaiDante

C # için IMO'ya bağlıdır: Açık arabirim uygulamaları kullanıyorsanız, uygulamayı belgelemem.

Bununla birlikte, arayüzü doğrudan uygularsanız ve arayüz üyelerini nesnenizle ortaya çıkarırsanız, bu yöntemlerin de belgelenmesi gerekir.

Nath'un dediği gibi, bir arabirimin belgelerini uygulamaya otomatik olarak eklemek için GhostDoc kullanabilirsiniz. Bu komutu Ctrl + Shift + D kısayoluna ve neredeyse otomatik olarak bastığım tuş vuruşlarından birine eşledim. ReSharper'ın sizin için yöntemleri uyguladığında arayüzün belgelerini ekleme seçeneğine de sahip olduğuna inanıyorum.

4
grover

Biz sadece arayüzü yorumluyoruz, yorumların türetilmiş veya temel sınıf/arayüz ile senkronize edilmemesi çok kolay, sadece tek bir yerde olması güzel.

@Nath gibi görünse de, belki bir şeyleri bir arada tutmaya yardımcı olan otomatik bir dokümantasyon aracı önerebilir (eğer kullanıyorsanız kulağa hoş geliyor). Burada WhereIWorkAndYouDontCare'de yorumlar dev içindir, bu nedenle kodda tek bir yer tercih edilir

4
Jiminy

Sadece arayüz. Her ikisini de yorumlamak çoğaltmadır ve iki değişiklik grubunun, kod değişirse sonuçta senkronize edilmemesi olasıdır. Uygulamayı "MyInterface uygular" ile yorumlayın ... Doxygen gibi şeyler, türemiş dokümanları uygulama için zaten dokümanlara içeren dokümanlar oluşturur (eğer doğru şekilde kurarsanız).

3
Len Holgate

Arayüzün yorumlanması, gerçek uygulamanın nasıl kullanılacağını bulmak için yeterli dokümantasyon olmalıdır. Uygulamaya yorum ekleyeceğim tek zaman, arayüzü tatmin etmek için eklenmiş özel işlevlere sahip olması, ancak bunlar yalnızca dahili yorumlar olacak ve çevrimiçi belgelerde görünmeyecek ya da müşterilere açık olmayacaktı.

Uygulamalar, ara yüze uygun oldukları sürece bunları ayrı ayrı belgelendirmeye gerek kalmamasıdır.

2
X-Istence

<İnheritdoc /> etiketi için destek eklemek üzere XML dokümantasyon dosyalarını işleyen bir araç yarattım.

Kaynak kodda Intellisense ile yardımcı olmamakla birlikte, değiştirilmiş XML dokümantasyon dosyalarının NuGet paketine dahil edilmesine izin verir ve bu nedenle başvurulan NuGet paketlerinde Intellisense ile çalışır.

Www.inheritdoc.io adresinde (ücretsiz sürüm mevcuttur).

0
K Johnson

Her ikisini de kesinlikle yorumlayabilirsiniz ancak daha sonra her ikisini de sürdürme probleminiz vardır (daha önce de belirtildiği gibi). Ancak, bu gün ve yaşta herhangi bir tüketen kod gerçekten IoC/DI kullanmayacak ve arayüzü kullanmayacak mı? Bunu göz önünde bulundurarak yalnızca bir yorum yapmaktan hoşlanıyorsanız, arayüzü yorumlamanızı şiddetle tavsiye ederim. Bu şekilde, kodunuzun tüketicisi, Nice intellisense ipuçlarını alması muhtemel olandan daha fazla olacaktır.

0
bytedev