Zwięzły opis w komentarzu przyczyny wyjątku czy ogólny?

W mojej aplikacji używam podobnych wyjątków co tutaj w przykładowym projekcie Netflixa https://github.com/Netflix/genie/tree/master/genie-common/src/main/java/com/netflix/genie/common/exceptions. Otóż chciałbym poznać Waszą opinię na temat sposobu opisywania przyczyn wyjątków w komentarzach. Gdy np. w metodzie serwisu wyrzucam wyjątki ResourceForbiddenException i ResourceNotFoundException, to w komentarzu wpisuję

/**
 * ...
 * @throws ResourceForbiddenException if no permissions
 * @throws ResourceNotFoundException if no contribution found or no user found
 */

można powiedzieć, że w miarę dokładnie opisuję dlaczego wystąpił wyjątek. Natomiast w tym przykładowym projekcie Netflix, programista nie opisuje dokładnie przyczyny wyjątku

/**
     * ...
     * @throws GenieException if there is an error
     */

wpisuje po prostu wyjątek z którego dziedziczą pozostałe i opisuje w skrócie np. if there is an error.

Uważacie, że w komentarzu należy napisać tylko ogólnie dlaczego występuje wyjątek, czy raczej zrobić to szczegółowo?

Nie widzę sensu by komentarz był tłumaczeniem na polski nazwy wyjątku.

Jeśli tworzysz bibliotekę, lub api, to dobrym pomysłem jest opisanie, dlaczego dany wyjątek jest rzucany.
np.:

    /**
     * Format input for further processing.
     *
     * @param input Input string.
     * @return Formatted String.
     * @throws WrongArgumentException Thrown if the input is incorrect (Incorrect format, or
     *                                unsupported operations)
     */
    private String prepareInput(String input) throws WrongArgumentException {

Jest informacja, ze jeśli dostarczysz nieprawidłowego Stringa, to zostanie rzucony taki wyjątek.
Tak samo dokumentacja java api:

public static Timestamp valueOf(String s)
Converts a String object in JDBC timestamp escape format to a Timestamp value.
Parameters:
s - timestamp in format yyyy-[m]m-[d]d hh:mm:ss[.f...]. The fractional seconds may be omitted. The leading zero for mm and dd may also be omitted.
Returns:
corresponding Timestamp value
Throws:
IllegalArgumentException - if the given argument does not have the format yyyy-[m]m-[d]d hh:mm:ss[.f...]

Tak, więc tak, jeśli robisz dokumentacje, to opisuj, czemu rzucasz dany wyjątek.

Mało kto czyta JavaDoce :-)
Poza tym:
http://memeagora.blogspot.ch/2008/11/comments-code-smell.html

Najlepiej poświęć czas na wymyślenie dobrej nazwy wyjątku i sformatowanie wiadomości (message) jaką wyjątek wyświetla.

To powinno starczyć. JavaDoc skasuj.

Dodatkowo : jeśli to biblioteka wewnętrzna (firmowa ) i nie dla szerokiego grona to zastanowiłbym się nad przerobieniem checked Exceptionów na Either, Try z Vavr.io.

u nas w pracy jest Sonar, który alarmuje, gdy jakiś javadoc jest niekompletny, czyli też gdy rzucany wyjątek jest nieopisany. I później trzeba tłumaczyć, że FileNotFoundException został wyrzucony ponieważ nie znaleziono pliku...

Tego Sonara to kosmici czy obce mocarstwo wam postawiło?

Jeżeli nazwa wyjątku mówi wszystko, to po co go opisywać? Ale, jeżeli już opisywać, to jednak nieco sensowniej niż "rzuciłem wyjątkiem, bo wyskoczył wyjątek". Coraz bardziej zastanawiam się czy statyczna analiza kodu, wymuszanie pokrycia i podobne wynalazki są takie super.

@diamen rozumiem że namiętnie opisujecie także gettery oraz settery? ;) Wiecie że da się sonara skonfigurować, prawda?

Nie, piszemy głównie javadoki do metod w interfejsach ;) (poza interfejsami też, ale tam już jest mniejszy rygor Sonara) Generalnie fajnie jest mieć opisane kiedy wyjątek występuje, ale tak jak pisałem w przypadku "FileNotFoundException", czasami jest to bezsensowne :)

A Sonarowe rule przychodzą od architeków ;)

Z architektami zwykle da się dogadać. I można takie reguły wyłączyć.
Jak się nie da dogadać to można wziąć kogoś bezużytecznego (np. scrum master) i kazać mu klikać won't fix na wszystkie takie.