如何记录在C＃/抛出的异常。网 [英] 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.

我要提供良好的智能感知信息，但我不知道的如何的文件抛出异常。

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>

我不明白的是如何记录抛出code异常调用 MyMethod1（）？

• 我应该记录抛出 MyMethod2异常（）
• 我应该记录抛出例外File.open方法（）？

• 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?

推荐答案

您应该记录可能由您的code抛出每个异常，包括在任何方法，您可以调用。

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应该简化多个异常成一个例外。让使用code更容易来电。

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.

---

要回答一些安德鲁的关注（从评论），有三种类型的异常：那些你不知道的，那些你知道的，不能做任何事情，你知道的人，可以做一些事情。

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异常不能做任何事情的人。在极端情况下，可能要处理这样的例外，但除非你有pretty的显着需求，你对待他们像第一类 - 让'时间去。你的有无的记录这些异常？你想看看pretty的愚蠢文档化奥姆斯在每一个方法，新s提高的对象。

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.

您可以找到处理这里除了一些准则。

You can find some more guidelines on exception handling here.

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