Belgeleme Arabirimleri ve bunların uygulanışı

Question

HTML yardım dosyalarını üretebilmem için C# kodumu yorumlarla yapıyorum.

Genellikle arabirimleri bildirir ve belgelerler. Ancak bu arayüzleri uygulayan sınıflar uygulamaya bağlı olarak belirli istisnalar atabilir.

Bazen, istemci yalnızca kullandığı arabirimlerin farkındadır. Uygulamacılarım tarafından atılabilecek olası istisnaları ekleyerek arayüzlerimi belgelemeli miyim?

Arabirim uygulayıcılarının bunları çerçevenin yerine atacak şekilde özel istisnalar oluşturmalı mıyım?

Umarım bu açıktır!

Teşekkür

DÜZENLEME 4 Ocak 2010

: Ben tam sorunuzu anlaşılamamıştır eminim http://blog.mikecouturier.com/2010/01/creating-custom-exceptions-in-net-right.html

Answer 1

de .NET bu ve özel istisnaları hakkında bir blog yazısı yazmaya karar (ve ben olduğum Java, C# geliştirici değil), ama aslında bir polimorfizm meselesi hakkında soru soruyor gibi görünüyor: eğer birisi X ve Y atmak için ilan edilen bir arabirimde bir yöntem kullanıyorsa, bir uygulama Z atarsa ​​ne olur? Takip edilecek bir şey, esas olarak bir alt türün, süper tip davranışına uygun olması gerektiğini ifade eden bir uyum ilkesidir. Yani, arabirimdeki yönteminizin yalnızca bir türden istisnalar (ör., Boş gösterici istisnaları) atabileceğini belgeliyorsanız, arayanlarla yaptığınız sözleşme, izlemeleri gereken tek şey budur. Başka bir şey atıyorsanız, onları şaşırtabilirsiniz.

Supertype'da belirli bir alt türle ilgili bir şeyler belgelemek, gereksiz bir kuplaj oluşturduğundan beri iyi bir fikir değildir. Bir uygulamanın beyandan farklı davrandığı gerçeğinden daha fazla endişeliyim çünkü bu, beyanın yeterli bir şekilde ortaya çıkmadığını düşündürüyor olabilir.

Yöntemin atabileceği tüm istisna türlerinin neler olduğunu düşünmeye çalışın. Onlar için üstbilgiler oluşturun ve daha sonra arabirim yönteminizde açık bir şekilde bildirin (örneğin, bu yöntem bir "hesaplama istisnası" verebilir). Ardından, uygulanmasında, daha fazla ayrıntı içeren bir hesaplama istisna veya uygulanmasına özgü hesaplama istisna bazı alt türünü atmak, hala uyum sağlayacaktır.

Answer 2

Uri'nin söylediği her şeyle aynı fikirdeyim - eğer mantıklı olarak istenirse genişletilebilen özel istisnalar oluşturmalısınız, o zaman arayüzünüze yazılan bir parametreyi kullanan bir yöntem bu istisnayı yakalayabilir ve alt tip özel durumları da yakalayabilir. Eğer yorumların sözleri bölümünü kullanabilirsiniz uygulayacaklar için belgeleyen açısından

('teşekkür varsayarak bu senin hata durumu kullanımını açıklayan mevcut .Net Framework istisna varsa

, gereksiz olsa bunları oluşturmayın XML yorumlarını kullanarak, uygulayıcıların işleri yapmasını nasıl beklediğiniz gibi şeyler tanımlamak. Açıkçası bu hiçbir şekilde uygulanabilir değildir ancak bir geliştirici API