исключения автодокумента на методах в [закрытом] C#/.NET
Я хотел бы некоторый инструмент, предпочтительно тот, который включает VS 2008/2010, который пройдет мои методы и добавит XML-комментарии о возможных исключениях, которые они могут выдать. Я не хочу <summary> или другие XML-тэги, которые будут сгенерированы для меня, потому что я заполню их сам, но это было бы хорошо если даже на private/protected методы, которые я видел, какие исключения могли быть выданы. Иначе я прохожу методы и колебаться на всех вызовах метода в них для наблюдения списка исключений, затем обновляя что метод <exception список для включения их. Возможно, макрос VS мог сделать это?
От этого:
private static string getConfigFilePath()
{
return Path.Combine(Environment.CurrentDirectory, CONFIG_FILE);
}
К этому:
/// <exception cref="System.ArgumentException"/>
/// <exception cref="System.ArgumentNullException"/>
/// <exception cref="System.IO.IOException"/>
/// <exception cref="System.IO.DirectoryNotFoundException"/>
/// <exception cref="System.Security.SecurityException"/>
private static string getConfigFilePath()
{
return Path.Combine(Environment.CurrentDirectory, CONFIG_FILE);
}
Обновление: кажется, что инструмент должен был бы пройти методы рекурсивно, например, method1 называет method2, который называет method3, который документируется как бросок NullReferenceException, так и method2 и method1 документируются инструментом, бросая NullReferenceException. Инструмент должен был бы также устранить дубликаты, как то, если два вызова в рамках метода документируются как бросок DirectoryNotFoundException, метод только перечислил бы <exception cref="System.IO.DirectoryNotFoundException"/> однажды.
4 ответа
Длинный и короткий ответ: это невозможно. В отличие от Java, ни один из языков .NET не требует, чтобы функции сообщали список возможных исключений, которые могут быть сгенерированы (что означает, что вы должны либо перехватывать, либо сообщать о любых исключениях, которые могут быть сгенерированы для функций, которые он вызывает). Из-за этого не существует универсального способа определить исчерпывающий список всех исключений, которые может генерировать функция (здесь я использую слово функция, чтобы охватить все, что написано как функция, включая операторы, конструкторы, и т. д.), потому что у вас нет гарантии относительно исключений, которые могут быть вызваны тем, что может вызвать данная функция.
Если вы хотите ограничиться, то вполне возможно, что вы могли бы написать что-то, что могло бы сканировать MSDN для соответствующей статьи для данного вызова библиотеки .NET и использовать там список исключений (если есть) для рекурсивного установления список того, что могло быть брошено. Однако это не будет охватывать какие-либо сторонние библиотеки или перехватывать любые исключения, создаваемые средой выполнения ( OutOfMemoryException , StackOverflowException , NullReferenceException [если вы не хотите сделайте еще один шаг и пусть ваш анализ исключений также определит, существует ли какая-либо возможность нулевой ссылки, но это тоже кажется невозможным в полностью общем смысле]).
Я почти уверен, что команда C # уже рассказывала об этом раз или два (я был бы удивлен, если бы Эрик Липперт еще не ответил на вопрос об этом на SO), но я почти уверен, что все сводилось к следующему: хотя такая система полезна и ценна для некоторых людей , обязательное ее использование (и принуждение вас либо сообщать, либо перехватывать все возможные исключения) привело к большому количеству попробуйте {...} catch (Exception ex) {...} блоки, чтобы избежать уборки, и общие, тихие уловы намного хуже (IMHO), чем незарегистрированное исключение.
RedGate Exception Hunter анализирует код на предмет возможного исключения. Возможно, вы могли бы использовать некоторые из его функций.
Exception Hunter из программного обеспечения RedGate поможет вам на полпути. Он может выполнять статический анализ вашего кода и показывать вам, какие исключения будут вызваны какими строками кода, включая вызовы .NET Framework. Он не будет писать за вас XML-документацию.
Но я должен сказать, что вы должны быть реалистами в отношении того, насколько полезным может быть такой инструмент ... существует ряд исключений, которые могут произойти в результате чрезвычайно необычных обстоятельств, таких как Система. OutOfMemoryException и System.ExecutionEngineException или в результате ошибки программиста, например System.NotImplementedException .Технически все это возможно, но на практике попытка задокументировать большинство из них для каждого метода не стоит вашего времени ... вы получите сотни строк комментариев практически для каждого метода в вашем приложении.
Вы можете частично удовлетворить свои требования, используя AtomineerUtils , который поддерживает документирование исключений.
Вы также можете использовать GhostDoc , Resharper и плагин Agent Johnson для генерации исключений. См. Следующий вопрос: Как документировать возникшие исключения в c # /. Net