C # / .net'te atılan istisnalar nasıl belgelenir

Şu anda şirket içindeki diğer geliştiriciler tarafından dahili olarak kullanılacak küçük bir çerçeve yazıyorum.

İyi Intellisense bilgileri sağlamak istiyorum, ancak atılan istisnaları nasıl belgeleyeceğimden emin değilim .

Aşağıdaki örnekte:

public void MyMethod1()
{
    MyMethod2();

    // also may throw InvalidOperationException
}

public void MyMethod2()
{
    System.IO.File.Open(somepath...); // this may throw FileNotFoundException

    // also may throw DivideByZeroException
}

İstisnaları belgelemek için biçimlendirme olduğunu biliyorum:

/// <exception cref="SomeException">when things go wrong.</exception>

Ne anlamıyorum tarafından çağrılan kod tarafından atılan istisnalar nasıl belgelenir MyMethod1()?

• Tarafından atılan istisnaları belgelemeli miyim MyMethod2()
• Tarafından atılan istisnaları belgelemeli miyim File.Open()?

Olası istisnaları belgelemenin en iyi yolu ne olabilir?

Kodunuz tarafından atılabilecek her istisnayı, arayabileceğiniz herhangi bir yöntem de dahil olmak üzere belgelemeniz gerekir.

Liste biraz büyürse, kendi istisna türünüzü oluşturmak isteyebilirsiniz. Metodunuzda karşılaşabileceğiniz her şeyi yakalayın, bunları istisnanıza sarın ve atın.

Bunu bu şekilde yapmak isteyebileceğiniz başka bir yer, yönteminiz API'nizin yüzündeyse. Tıpkı bir cephenin çoklu arayüzleri tek bir arayüzde basitleştirmesi gibi, API'niz de çoklu istisnaları tek bir istisnada basitleştirmelidir. Kodunuzu arayanlar için kullanımını kolaylaştırır.

Andrew'un bazı endişelerini yanıtlamak için (yorumlardan), üç tür istisna vardır: Bilmediğiniz, bildiğiniz ve hakkında bir şey yapamayanlar ve bildiğiniz ve hakkında bir şeyler yapabilecek olanlar.

Senin hakkında bilmediklerini bırakmak istiyorlar. Bu hızlı başarısız ilkesi - verilerinizi bozan bir durum girmek daha app çökmesine daha iyi. Çökme size neler olduğunu ve nedenini anlatacak, bu da bu istisnayı "bilmedikleriniz" listesinden çıkarmanıza yardımcı olabilir.

Bildiğiniz ve yapamayacağınız şeyler OutOfMemoryExceptions gibi istisnalardır. Aşırı durumlarda, bunun gibi istisnaları ele almak isteyebilirsiniz, ancak oldukça dikkat çekici gereksinimleriniz yoksa, onlara ilk kategori gibi davranırsınız - hadi gidelim. Eğer Do sahip bu istisnaları belgelemek için? Bir nesneyi yeni oluşturan her yöntemde OOM'ları belgelemek oldukça aptalca görünecektir.

Bildiğiniz ve hakkında bir şeyler yapabileceğiniz, belgelendirmeniz ve paketlemeniz gerekenlerdir.

İstisna işlemeyle ilgili daha fazla yönergeyi burada bulabilirsiniz.

Standart xml belgelerini kullanmalısınız .

/// <exception cref="InvalidOperationException">Why it's thrown.</exception>
/// <exception cref="FileNotFoundException">Why it's thrown.</exception>
/// <exception cref="DivideByZeroException">Why it's thrown.</exception>
public void MyMethod1()
{
    MyMethod2();
    // ... other stuff here
}

/// <exception cref="FileNotFoundException">Why it's thrown.</exception>
/// <exception cref="DivideByZeroException">Why it's thrown.</exception>
public void MyMethod2()
{
    System.IO.File.Open(somepath...);
}

/// <exception cref="FileNotFoundException">Why it's thrown.</exception>
public void MyMethod3()
{
    try
    {
        MyMethod2();
    }
    catch (DivideByZeroException ex)
    {
        Trace.Warning("We tried to divide by zero, but we can continue.");
    }
}

Bu şekilde yapmanın değeri, oluşabilecek bilinen istisnaların belgelerini sağlamanızdır. Görsel dokümantasyon kullanıyorsanız ve size (veya diğerlerini) daha sonra bekleyebileceğiniz istisnaları hatırlatabiliyorsa, bu dokümantasyon bilgi bölümünde mevcuttur.

Belirli istisna türlerini belirtmek istersiniz, çünkü diğer türler ciddi bir sorunun sonucudur ve düzeltilemez.

Birkaç harika eklenti kullanarak dokümantasyon sürecinizi kolaylaştırabilirsiniz. Bunlardan biri, XML-doc yorumları üreten Visual Studio için ücretsiz bir eklenti olan GhostDoc . Ayrıca, ReSharper kullanıyorsanız , atılan istisnalar için XML yorumları oluşturmak için bir seçenek ekleyen ReSharper için mükemmel Ajan Johnson Eklentisine bir göz atın .

Güncelleme: Görünüşe göre Agen Johnson, R # 8 için mevcut değil, alternatif olarak ReSharper için olağanüstü ödeme ...

Adım 1: GhostDoc XML yorumunu (Ctrl-Shift-D) oluşturur, ReSharper için Agent Johnson eklentisi de istisnayı belgelemeyi önerir:

2. Adım: İstisna belgelerini eklemek için ReSharper'ın kısayol tuşunu (Alt-Enter) kullanın:

adım 2 http://i41.tinypic.com/osdhm

Umarım yardımcı olur :)

Anladığım kadarıyla, <exception> öğesini kullanmanın amacı, istisnalar değil, dekorasyon yöntemlerinde kullanmaktır:

/// <summary>Does something!</summary>
/// <exception cref="DidNothingException">Thrown if nothing is actually done.</exception>
public void DoSomething()
{
// There be logic here
}

Çağrılan diğer yöntemlerle atılabilecek istisnalar, bu yöntemlerde yakalanmalı, ele alınmalı ve belgelenmelidir. .NET tarafından atılabilecek özel durumlar veya açıkça kendi kodunuz tarafından atılan özel durumlar belgelenmelidir.

Bundan daha spesifik hale geldikçe, belki kendi özel istisnalarınızı yakalayıp atabilirsiniz?

Yöntemin sözleşmesinin bir kısmı, ön koşulların geçerli olup olmadığını kontrol etmek olmalıdır, bu nedenle:

public void MyMethod2()
{
    System.IO.File.Open(somepath...); // this may throw FileNotFoundException
}

olur

/// <exception cref="FileNotFoundException">Thrown when somepath isn't a real file.</exception>
public void MyMethod2()
{
    FileInfo fi = new FileInfo( somepath );
    if( !fi.Exists )
    {
        throw new FileNotFoundException("somepath doesn't exists")
    }
    // Maybe go on to check you have permissions to read from it.

    System.IO.File.Open(somepath...); // this may still throw FileNotFoundException though
}

Bu yaklaşımla, atılmış OutOfMemoryException olabileceğini belgelemek zorunda kalmadan açıkça attığınız tüm istisnaları belgelemek daha kolaydır .

Yönteminiz tarafından atılabilecek tüm istisnaları belgelemeniz gerekir.

Uygulama ayrıntılarını gizlemek için MyMethod2'den bazı istisnaları kendim ele almaya çalışacağım.

İstisna ile başa çıkamaz veya çözemezseniz, onları geri almayı düşünebilirsiniz. Çoğunlukla arayan için daha anlamlı bir istisna halinde paketlenir / paketlenir.

Aslında, daha önce yanıtlandığı gibi, istisnaları belgelemenin yolu XML Yorumları kullanmaktır.

Eklentilere ek olarak, istisnaların belgelendiğinden emin olmak için TFS ile entegre edilebilen statik analiz araçlarını da kullanabilirsiniz.

Aşağıdaki bağlantılarda, StyleCop için yöntemlerinizin oluşturduğu özel durumları doğrulamak üzere nasıl özel bir kural oluşturulacağını görebilirsiniz.

http://www.josefcobonnin.com/post/2009/01/11/Xml-Documentation-Comments-Exceptions-I.aspx http://www.josefcobonnin.com/post/2009/01/15/Xml-Documentation -Yorumlar-İstisnalar-II.aspx

Saygılarımızla.

Yöntemin beklenen istisnalar Belgenizde, örneğinizde kullanıcıya bu yöntemin istisna bulunmayan bir dosyayı atabileceğini bildiririm.

Unutmayın, arayanla ne bekleyeceğini bildirmek, böylece onunla nasıl başa çıkılacağını seçebilirler.