如何在c＃/。net文件中抛出异常 [英] How to document thrown exceptions in c#/.net

问题描述

我目前正在撰写一个小型框架，将由公司内其他开发人员在内部使用。

I am currently writing a small framework that will be used internally by other developers within the company.

我想提供良好的Intellisense信息，但我不确定

I want to provide good Intellisense information, but I am not sure how to document thrown exceptions.

在以下示例中：

public void MyMethod1()
{
    MyMethod2();

    // also may throw InvalidOperationException
}

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

    // also may throw DivideByZeroException
}

我知道记录异常的标记是：

I know the markup for documenting exceptions is:

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

我不明白的是如何记录由调用的代码 MyMethod1（）？

What I don't understand is how to document exceptions thrown by code called by MyMethod1()?

• 我应该记录 MyMethod2（）


• 我应该记录由 File.Open（） / li>
  

• Should I document exceptions thrown by MyMethod2()
• Should I document exceptions thrown by File.Open() ?

什么是记录可能的异常的最佳方法？

What would be the best way to document possible exceptions?

推荐答案

您应该记录您的代码可能抛出的每个异常，包括您可能会调用的任何方法中的任何异常。

You should document every exception that might be thrown by your code, including those in any methods that you might call.

如果列表获得有点大，你可能想要创建自己的异常类型。抓住你在方法中遇到的所有可能的东西，将它们包装在异常中，并抛出它。

If the list gets a bit big, you might want to create your own exception type. Catch all the ones you might encounter within your method, wrap them in your exception, and throw that.

另一个你想要这样做的地方是你的方法在你的API面前。就像立面简化将多个接口简化为一个接口，您的API应该将多个异常简化为一个异常。使用您的代码更容易呼叫者。

Another place you might want to do it this way is if your method is on the face of your API. Just like a facade simplifies multiple interfaces into a single interface, your API should simplify multiple exceptions into a single exception. Makes using your code easier for callers.

要回答Andrew的一些担忧（从评论中），有三种类型例外：你不知道，你知道的，你不知道的，也不能做任何事情，而且你可以做些什么，可以做些什么。

To answer some of Andrew's concerns (from the comments), there are three types of exceptions: Ones you don't know about, ones you know about and can't do anything about, and ones you know about and can do something about.

你不知道你想放弃的那些人。它的失败的原因是快速 - 更好的你的应用程序崩溃进入一个状态，你可能会最终破坏你的数据。崩溃会告诉你发生了什么，为什么，这可能有助于将这个例外从你不了解的列表中移除。

The ones you don't know about you want to let go. Its the principal of failing fast--better your app to crash than enter a state where you might end up corrupting your data. The crash will tell you about what happened and why, which may help move that exception out of the "ones you don't know about" list.

你知道的关于和不能做任何事情是例外，如OutOfMemoryExceptions。在极端情况下，您可能想要处理这样的异常，但除非您有一些非常显着的要求，否则您会将其视为第一类 - 让我们走。您是否拥有来记录这些异常？你会看起来非常愚蠢的记录OOMs的每一个方法，新的一个对象。

The ones you know about and can't do anything about are exceptions like OutOfMemoryExceptions. In extreme cases you might want to handle exceptions like this, but unless you have some pretty remarkable requirements you treat them like the first category--let 'em go. Do you have to document these exceptions? You'd look pretty foolish documenting OOMs on every single method that new-s up an object.

你所了解的和可以做的事情是你应该记录和包装的那些。

The ones you know about and can do something about are the ones you should be documenting and wrapping.

您可以找到更多这里的异常处理指南。

这篇关于如何在c＃/。net文件中抛出异常的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！