Как документировать выданные исключения в c# / .net [закрыто]

вы должны использовать стандартная xml-документация.

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

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

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

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

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

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

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

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

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

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

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

надеюсь, что это поможет:)

из того, что я понимаю, намерение использовать элемент состоит в том, чтобы использовать его при оформлении методов, а не исключений:

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

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

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

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

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
}

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

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

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

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

действительно, как уже было сказано, способ документирования исключений-это использование комментариев 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

с уважением.

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

помните, что он должен информировать абонента о том, чего ожидать, чтобы они могли выбрать, как с этим бороться.