Arayüzü, uygulamayı veya her ikisini birden yorumluyor musunuz?

Hepimizin (rahatsız olabileceğimiz zaman!) Arayüzlerimizi yorumladığımızı 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 (müşterilere, örneğin bir kütüphanenin bir parçası olarak da sunulabilir)? Öyleyse, ikisini uyumlu halde tutmayı nasıl yönetiyorsunuz? Yoksa sadece 'Belgeler için arayüze bakın' açıklaması mı ekliyorsunuz?

Teşekkürler

Genel bir kural olarak, kodla aynı KURU (Kendini Tekrar Etme) prensibini kullanıyorum:

• arayüzde, arayüzü belgeleyin
• uygulama hakkında, uygulama özelliklerini belgeleyin

Java'ya özgü : Uygulamayı belgelerken, arayüzden javadoc'ları "dahil etmek" için {@inheritDoc} etiketini kullanın.

Daha fazla bilgi için:

• Resmi javadoc belgeleri
• Resmi olmayan bazı tavsiyeler .

GhostDoc eklentisini kullanırsanız, sağ tıklayıp yöntemde "Bunu Belgeleme" seçeneğini seçtiğinizde arayüzden gelen yorumla uygulamayı günceller.

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

Bununla birlikte, arayüzü doğrudan uygularsanız ve arayüzün üyelerini nesnenizle ifşa ederseniz, bu yöntemlerin de belgelenmesi gerekir.

Nath'in dediği gibi, bir arayüzün belgelerini uygulamaya otomatik olarak eklemek için GhostDoc'u kullanabilirsiniz. Belgeyi 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 uygularken arayüzün belgelerini ekleme seçeneğine de sahip olduğuna inanıyorum.

Yalnızca arayüz. Her ikisine de yorum yapmak yinelemedir ve muhtemelen kod değişirse iki yorum grubu da sonunda senkronize olmayacaktır. Uygulamayı "MyInterface uygular" ile yorumlayın ... Doxygen gibi şeyler, türetilmiş dokümanları yine de uygulama için dokümanlara dahil eden dokümanlar oluşturacaktır (bunları doğru bir şekilde ayarladıysanız).

Sadece arayüzü yorumluyoruz, yorumların türetilmiş veya temel sınıf / arayüzle senkronize olmaması o kadar kolay ki, tek bir yerde olması güzel.

@Nath, işleri bir arada tutmaya yardımcı olan otomatik bir dokümantasyon aracı öneriyor gibi görünse de (bunu kullanırsanız harika geliyor). Burada WhereIWorkAndYouDontCare'de yorumlar dev içindir, bu nedenle kodda tek bir yer tercih edilir

Arayüz hakkında yorum yapmak, gerçek uygulamanın nasıl kullanılacağını anlamak için yeterli belge olmalıdır. Uygulamaya yorum ekleyeceğim tek zaman, arayüzü tatmin etmek için eklenen özel işlevlere sahip olması, ancak bunlar yalnızca dahili yorumlar olacak ve çevrimiçi belgelerde görünmeyecek veya istemciler tarafından kullanılamayacak.

Uygulamalar, arayüze uydukları sürece ayrı ayrı belgelendirmeye gerek yoktur.

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

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

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

Her ikisini de kesinlikle yorumlayabilirsiniz, ancak o zaman her ikisini de sürdürme problemi yaşarsınız (daha önce belirtildiği gibi). Bununla birlikte, bu gün ve çağda, herhangi bir tüketici kod gerçekten IoC / DI kullanmayacak ve arayüzü kullanmayacak mı? Bu göz önüne alındığında, yalnızca bir tanesini yorumlamakla uğraşmak istiyorsanız, arayüzü yorumlamanızı şiddetle tavsiye ederim. Bu şekilde, kodunuzun tüketicisi muhtemelen güzel intellisense ipuçlarını elde edecektir.

C # kullanımı:

Arayüz şöyle görünebilir:

    /// <summary>
    /// Helper class to access various properties for the current site.
    /// </summary>
    public interface ISiteHelper
    {
        /// <summary>
        /// Gets the site id of the current site
        /// </summary>
        /// <returns>The site id.</returns>
        int GetSiteID();
    }
}

Uygulama şu şekilde görünebilir:

/// <inheritdoc />
public class SiteHelper: ISiteHelper
{
    /// <inheritdoc />
    public int GetSiteID()
    {
        return CommonRepository.GetSiteID();
    }
}