Является ли хорошей практикой документировать выброшенные исключения для интерфейсов?

Question

Как гласит название: хорошо ли документировать заброшенные исключения для интерфейсов? Существует ли вообще согласованная передовая практика? Я чувствую, что это деталь реализации, которая никак не должна быть включена в интерфейс, но в то же время я считаю, что это ценная информация, которую должен иметь пользователь интерфейса.

Является ли такая рекомендация хорошей практикой, является темой для другого обсуждения, поэтому, чтобы ограничить сферу этого вопроса, предположим, что мы согласились с тем, что документирование кода с комментариями, как это, является хорошей практикой. Здесь, с такими комментариями, я имею в виду комментарии, которые вы можете генерировать, например, документацию или метаданные, а не только «нормальные» комментарии. Примеры включают документацию XML, Javadoc и Doxygen.

Теперь, какой из этих примеров C# является лучшей практикой, если можно даже договориться о какой-либо лучшей практике?

интерфейс без документации исключения:

public interface IMyInterface { 
    /// <summary> 
    /// Does something. 
    /// </summary> 
    void DoSomething(); 
} 

Интерфейс с документацией исключения:

public interface IMyInterface { 
    /// <summary> 
    /// Does something. 
    /// </summary> 
    /// <exception cref="System.Exception">Something went wrong.</exception> 
    void DoSomething(); 
} 

Answer 1

Интерфейсы контрактов, если часть этого договора включает в себя ситуацию, выброшенное исключение вы должны обязательно включить его в вашей документации. Вы можете видеть примеры исключений, задокументированных в интерфейсах по всей платформе .NET, например, IEnumerator имеет немало. (Текст retreived щелкнув правой кнопкой мыши на объявлении IEnumerator и навигации на «представление метаданных»)

public interface IEnumerator 
    { 
    /// <summary> 
    /// Advances the enumerator to the next element of the collection. 
    /// </summary> 
    /// 
    /// <returns> 
    /// true if the enumerator was successfully advanced to the next element; false if the enumerator has passed the end of the collection. 
    /// </returns> 
    /// <exception cref="T:System.InvalidOperationException">The collection was modified after the enumerator was created. </exception><filterpriority>2</filterpriority> 
    bool MoveNext(); 
    /// <summary> 
    /// Sets the enumerator to its initial position, which is before the first element in the collection. 
    /// </summary> 
    /// <exception cref="T:System.InvalidOperationException">The collection was modified after the enumerator was created. </exception><filterpriority>2</filterpriority> 
    void Reset(); 
    /// <summary> 
    /// Gets the current element in the collection. 
    /// </summary> 
    /// 
    /// <returns> 
    /// The current element in the collection. 
    /// </returns> 
    /// <filterpriority>2</filterpriority> 
    object Current { get; } 
    } 

Answer 2

Интерфейс только определяет контракт операций делать не так, как они реализуются. Рассмотрим следующий пример:

void Sort(SortOrder order); 

Вы могли бы возникнуть соблазн добавить комментарий throws ArgumentNullException if order is null, но что произойдет, если реализатор интерфейса решает, что получение нуль на SortOrder означает, что он должен использовать по умолчанию SortOrder? (неправильное решение, но возможное). Это должно быть правильным решением для одного интерфейса, и если это не вариант, чтобы решить такие вещи, то вы должны предложить абстрактный базовый класс, который генерирует исключение вместо интерфейса.

Добавление исключений к интерфейсам подобно тому, как наследование интерфейсов наследуется от интерфейса IDisposable. Эти вещи являются деталями реализации, которые не должны вникать в определение интерфейса.