异常文档的 C# 准则

标签 c#

<分区>

我正在处理的 API 变得相当大，现在我正在处理一些多线程的东西，所以我想确保我知道在任何给定点可能发生的所有异常。我知道 C# 没有必须为每个方法声明的已检查异常，如 Java，但我想我会在每个方法的文档中这样做。

考虑以下非常简单的示例:

/// <exception cref="System.DivideByZeroException">oh no, divide by zero.</exception>
int someMethod(int a, int b)
{
    return a / b; //this might throw DivideByZeroException
}

//clearly this method can never throw a DivideByZeroException
int someOtherMethod(int a)
{
    return someMethod(a, 2);
}

我是否将 DivideByZeroException 标记添加到“someOtherMethod”？

当然这只是一个非常简单的例子，真正的代码更复杂，但有时我知道一个子方法抛出的异常永远不会发生。不是因为我捕获了它，而是因为我总是会向它传递有效的参数。

如果我想要异常文档，那么我有 3 个选项:

1) 表现得好像那个异常永远不会发生并且不将标记添加到文档中(因为它永远不会发生，而且我有单元测试来支持它)。

2) 为我知道永远不会发生的异常添加异常标记。

3) try catch 并忽略，以确保它永远不会发生，因此我可以有意识地将它从异常列表中删除。

我最喜欢选项 1，但是对此有任何指导方针吗？

最佳答案

我从未见过与此相关的任何类型的指南，但开发人员大多是有逻辑的人，他们希望在文档中看到可能发生的异常，而永远不会看到那些不会发生的异常。合乎逻辑，这通常比遵循准则要好得多(当然这也很重要)。

关于异常文档的 C# 准则，我们在Stack Overflow上找到一个类似的问题： https://stackoverflow.com/questions/28083001/