Obecnie piszę mały framework, który będzie używany wewnętrznie przez innych programistów w firmie.
Chcę zapewnić dobre informacje Intellisense, ale nie jestem pewien, jak udokumentować zgłoszone wyjątki.
W poniższym przykładzie:
public void MyMethod1()
{
MyMethod2();
// also may throw InvalidOperationException
}
public void MyMethod2()
{
System.IO.File.Open(somepath...); // this may throw FileNotFoundException
// also may throw DivideByZeroException
}
Wiem, że znaczniki dokumentujące wyjątki to:
/// <exception cref="SomeException">when things go wrong.</exception>
Nie rozumiem, jak dokumentować wyjątki wyrzucane przez kod wywoływany przez MyMethod1()
?
- Czy powinienem dokumentować wyjątki zgłoszone przez
MyMethod2()
- Czy powinienem dokumentować wyjątki zgłoszone przez
File.Open()
?
Jaki byłby najlepszy sposób udokumentowania możliwych wyjątków?
c#
.net
documentation
intellisense
Arnold Zokas
źródło
źródło
Odpowiedzi:
Powinieneś udokumentować każdy wyjątek, który może zostać wyrzucony przez twój kod, w tym te z wszelkich metod, które możesz wywołać.
Jeśli lista stanie się trochę duża, możesz chcieć utworzyć własny typ wyjątku. Złap wszystkie te, które możesz napotkać w swojej metodzie, zawiń je w wyjątek i wyrzuć to.
Innym miejscem, w którym możesz chcieć to zrobić w ten sposób, jest to, że Twoja metoda znajduje się w interfejsie API. Podobnie jak fasada upraszcza wiele interfejsów do jednego interfejsu, Twój interfejs API powinien uprościć wiele wyjątków do jednego wyjątku. Ułatwia korzystanie z Twojego kodu dzwoniącym.
Aby odpowiedzieć na niektóre obawy Andrzeja (z komentarzy), istnieją trzy rodzaje wyjątków: takie, o których nie wiesz, takie, o których wiesz i nie możesz nic zrobić, oraz takie, o których wiesz i możesz coś zrobić.
Te, o których nie wiesz, chcesz odpuścić. Jest to podstawa szybkiego niepowodzenia - lepiej, aby aplikacja uległa awarii, niż wejdź w stan, w którym możesz uszkodzić dane. Awaria powie Ci, co się stało i dlaczego, co może pomóc usunąć ten wyjątek z listy „tych, o których nie wiesz”.
Te, o których wiesz i nie możesz nic zrobić, to wyjątki, takie jak OutOfMemoryExceptions. W skrajnych przypadkach możesz chcieć obsłużyć takie wyjątki, ale jeśli nie masz jakichś dość niezwykłych wymagań, traktujesz je jak pierwszą kategorię - pozwól im odejść. Czy mają udokumentować te wyjątki? Wydawałbyś się całkiem głupi dokumentując OOM dla każdej metody, która powoduje nowy obiekt.
Te, o których wiesz i możesz coś zrobić, to te, które powinieneś dokumentować i pakować.
Więcej wskazówek dotyczących obsługi wyjątków można znaleźć tutaj.
źródło
Powinieneś użyć standardowej dokumentacji xml .
Wartością robienia tego w ten sposób jest dostarczenie dokumentacji znanych wyjątków, które mogą wystąpić. Ta dokumentacja jest dostępna w trybie Intellisense, jeśli używasz programu Visual Studio i może później przypomnieć tobie (lub innym) o wyjątkach, których możesz się spodziewać.
Chcesz określić konkretne typy wyjątków, ponieważ możesz być w stanie obsłużyć jeden typ wyjątków, podczas gdy inne typy są wynikiem poważnego problemu i nie można ich naprawić.
źródło
Możesz ułatwić sobie proces tworzenia dokumentacji, używając kilku świetnych dodatków. Jednym z nich jest GhostDoc , darmowy dodatek do programu Visual Studio, który generuje komentarze XML-doc. Ponadto, jeśli używasz ReSharper , spójrz na doskonałą wtyczkę Agent Johnson dla ReSharper, która dodaje opcję generowania komentarzy XML dla wyrzuconych wyjątków.
Aktualizacja: Wygląda na to, że Agen Johnson nie jest dostępny dla R # 8, sprawdź Wyjątkowy dla ReSharper jako alternatywa ...
krok 2 http://i41.tinypic.com/osdhm
Mam nadzieję, że to pomoże :)
źródło
Z tego co rozumiem, intencją użycia elementu <exception> jest użycie go przy dekorowaniu metod, a nie wyjątków:
Wyjątki, które mogą być generowane przez inne wywoływane metody, powinny być przechwytywane, obsługiwane i dokumentowane w tych metodach. Należy udokumentować wyjątki, które mogą być generowane przez platformę .NET, lub wyjątki jawnie zgłaszane przez Twój własny kod.
Jeśli chodzi o uzyskanie bardziej szczegółowych informacji, być może uda Ci się wyłapać i wrzucić własne niestandardowe wyjątki?
źródło
Częścią kontraktu dla twojej metody powinno być sprawdzenie, czy warunki wstępne są ważne, więc:
staje się
Dzięki takiemu podejściu łatwiej jest udokumentować wszystkie wyjątki, które jawnie zgłaszasz, bez konieczności dokumentowania, że
OutOfMemoryException
może zostać wyrzucony itp.źródło
Open
by wywołać (nie wspominając, jak zauważyłeś, że jest wyścig, a czek nie gwarantuje sukcesuOpen
). ,Powinieneś udokumentować wszystkie wyjątki, które mogą zostać wyrzucone przez twoją metodę.
Aby ukryć szczegóły implementacji, spróbuję samodzielnie obsłużyć niektóre wyjątki z MyMethod2.
Możesz rozważyć ich odzyskanie, jeśli nie możesz obsłużyć lub rozwiązać wyjątku. Przeważnie zapakowane / opakowane w bardziej znaczący wyjątek dla dzwoniącego.
źródło
Rzeczywiście, jak już udzielono odpowiedzi, sposobem udokumentowania wyjątków jest użycie komentarzy XML.
Oprócz wtyczek można również użyć narzędzi do analizy statycznej, które można zintegrować z TFS, aby mieć pewność, że wyjątki są udokumentowane.
W poniższych linkach możesz zobaczyć, jak zbudować niestandardową regułę dla StyleCop, aby sprawdzić poprawność wyjątków generowanych przez twoje metody.
http://www.josefcobonnin.com/post/2009/01/11/Xml-Documentation-Comments-Exceptions-I.aspx http://www.josefcobonnin.com/post/2009/01/15/Xml-Documentation -Comments-Exceptions-II.aspx
Pozdrowienia.
źródło
Dokumentuj oczekiwane wyjątki w swojej metodzie, w twoim przykładzie chciałbym poinformować użytkownika, że ta metoda może zgłosić wyjątek nie znaleziono pliku.
Pamiętaj, że ma to na celu poinformowanie dzwoniącego o tym, czego może się spodziewać, aby mógł wybrać, jak sobie z tym poradzić.
źródło