Как документировать выброшенные исключения в С#/. Net

В настоящее время я пишу небольшую структуру, которая будет использоваться внутри других разработчиков внутри компании.

Я хочу предоставить хорошую информацию Intellisense, но я не уверен, как документировать заброшенные исключения.

В следующем примере:

public void MyMethod1()
{
    MyMethod2();

    // also may throw InvalidOperationException
}

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

    // also may throw DivideByZeroException
}

Я знаю, что разметка для документирования исключений:

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

Я не понимаю, как документировать исключения, создаваемые кодом , вызываемым MyMethod1()?

  • Должен ли я документировать исключения, сброшенные MyMethod2()
  • Должен ли я документировать исключения, отбрасываемые File.Open()?

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

ОТВЕТЫ

Ответ 1

Вы должны задокументировать все исключения, которые могут быть брошены вашим кодом, в том числе в любых методах, которые вы могли бы назвать.

Если список становится немного большим, вы можете создать свой собственный тип исключения. Поймайте все те, с которыми вы можете столкнуться в своем методе, оберните их в свое исключение и бросьте это.

Еще одно место, которое вы, возможно, захотите сделать так, - это ваш метод на лицевой стороне вашего API. Подобно тому, как фасад упрощает несколько интерфейсов в один интерфейс, ваш API должен упростить несколько исключений в одном исключении. Делает ваш код более удобным для абонентов.

Чтобы ответить на некоторые из проблем Эндрю (из комментариев), существует три типа исключений: о вас, о которых вы не знаете, о тех, о которых знаете и которые не можете что-либо сделать, и о тех, о которых вы знаете и можете делать что-то о.

Те, о которых вы не знаете, хотите отпустить. Его главный недостаток быстро - лучше ваше приложение для краха, чем введите состояние, в котором вы могли бы повредить ваши данные. Крушение расскажет вам о том, что произошло и почему, что может помочь переместить это исключение из списка "тех, кого вы не знаете".

Те, о которых вы знаете, и не можете ничего сделать, - это исключения, такие как OutOfMemoryExceptions. В крайних случаях вы, возможно, захотите обрабатывать такие исключения, но если у вас нет каких-то довольно замечательных требований, вы относитесь к ним как к первой категории - пусть они уйдут. Вам нужно документировать эти исключения? Вы бы выглядели довольно глупо, документируя OOM по каждому методу, что новый объект.

Те, о которых вы знаете и можете что-то сделать, - это те, которые вы должны документировать и обертывать.

Здесь вы можете найти еще рекомендации по обработке исключений.

Ответ 2

Вы должны использовать стандартную XML-документа .

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

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

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

Значение при этом заключается в том, что вы предоставляете документацию об известных исключениях, которые могут произойти. Эта документация доступна в intellisense, если вы используете визуальную студию и можете напомнить вам (или другим) о тех исключениях, которые вы можете ожидать.

Вы хотите указать конкретные типы исключений, поскольку вы можете обрабатывать один тип исключения, в то время как другие типы являются результатом серьезной проблемы и не могут быть исправлены.

Ответ 3

Вы можете упростить процесс документирования, используя несколько замечательных надстроек. Одним из них является GhostDoc, бесплатная надстройка для Visual Studio, которая генерирует комментарии XML-doc. Кроме того, если вы используете ReSharper, посмотрите на отличный агент Johnson Plugin для ReSharper, который добавляет возможность генерировать комментарии XML для исключенных исключений.

Обновление: Кажется, что Agen Johnson недоступен для R # 8, checkout Исключительно для ReSharper в качестве альтернатива...

Шаг 1: GhostDoc генерирует XML комментарий (Ctrl-Shift-D), а плагин Agent Johnson для ReSharper предлагается документировать исключение:

шаг 1 http://i44.tinypic.com/bdwsk0.png

Шаг 2: Используйте горячую клавишу ReSharper (Alt-Enter), чтобы добавить исключение документация:

шаг 2 http://i41.tinypic.com/osdhm

Надеюсь, что помогает:)

Ответ 4

Из того, что я понимаю, намерение использовать <exception> элемент должен использовать его при использовании методов украшения, а не исключений:

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

Исключения, которые могут быть вызваны другими вызванными способами, должны быть пойманы, обработаны и задокументированы в этих методах. Исключения, которые могут быть выброшены .NET, или исключения, которые явно выбраны вашим собственным кодом, должны быть задокументированы.

Что же касается получения более конкретной информации, возможно, вы можете поймать и выбросить свои собственные индивидуальные исключения?

Ответ 5

Часть контракта для вашего метода должна состоять в том, чтобы проверить, что предварительные условия действительны, поэтому:

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

становится

/// <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
}

При таком подходе легче документировать все исключения, которые вы явно бросаете, не имея необходимости также документировать, что может быть выброшено OutOfMemoryException и т.д.

Ответ 6

Вы должны задокументировать все исключения, которые могут быть вызваны вашим методом.

Чтобы скрыть детали реализации, я попытался бы обработать некоторые исключения из MyMethod2 самостоятельно.

Вы можете подумать о том, чтобы перестроить их, если вы не можете справиться или решить исключение. В основном упакован/завернут в более значимое исключение для вызывающего.

Ответ 7

Действительно, как уже было сказано, способ документировать исключения - это использование комментариев XML.

В дополнение к плагинам вы также можете использовать инструменты статического анализа, которые могут быть интегрированы с TFS, чтобы убедиться, что вы задокументировали исключения.

В приведенных ниже ссылках вы можете увидеть, как создать настраиваемое правило для StyleCop для проверки исключений, созданных вашими методами, задокументированы.

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

С уважением.

Ответ 8

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

Помните, что это нужно сообщить вызывающему о том, чего ожидать, чтобы они могли выбрать, как с этим бороться.