在python DocString中记录其他函数中可能发生的异常
在Python中,除了在当前函数/方法主体中提出的异常之外,我们是否应该在docstrings中记录可以在其他函数/类中提出的异常 Obs:我正在考虑Google Python文档字符串样式 我已经很久没有玩Java了,但是在那里你可以明确地说你的方法可以用“throws”关键字引发什么样的异常 例如:在python DocString中记录其他函数中可能发生的异常,python,exception,documentation,docstring,Python,Exception,Documentation,Docstring,在Python中,除了在当前函数/方法主体中提出的异常之外,我们是否应该在docstrings中记录可以在其他函数/类中提出的异常 Obs:我正在考虑Google Python文档字符串样式 我已经很久没有玩Java了,但是在那里你可以明确地说你的方法可以用“throws”关键字引发什么样的异常 例如: 是的,您应该记录bar()(和foo())会引发MyException。通过这种方式,对于任何即将使用bar()的人来说,调用它时会发生哪些异常都是显而易见的。如果您试图记录您的函数可以抛出的每
是的,您应该记录
bar()
(和foo()
)会引发MyException
。通过这种方式,对于任何即将使用bar()
的人来说,调用它时会发生哪些异常都是显而易见的。如果您试图记录您的函数可以抛出的每个异常,那么是的,您应该包含可以通过您调用的内容抛出的函数。否则,你的清单不仅毫无用处,而且会产生误导。如果你用具体的案例而不是抽象和无意义的案例来思考,这一点就会变得显而易见。例如,如果调用我的distance
函数,它记录了它可以引发一系列不同的异常,但不是一个DivideByZero,那么你将认为这意味着调用我的函数永远不会得到一个DivideByZero。如果你得到一个,它最初来自我的函数调用的其他函数并不重要;我的函数坏了。这个规则的一个例外是,如果你传入一个回调函数,我调用你的回调函数,而你提出了一些我从未听说过的异常,我可能会也可能不会传递给你。这两种方法都是可以接受的,但在这种情况下,无论我选择哪种方法,都可能是文档,在列表的末尾添加“以及回调参数引发的任何异常”之类的内容。这是否回答了您的问题?
class MyException(Exception):
pass
class A(object):
def foo(self):
"""This class does foo
Returns:
Int: The number of foo.
Raises:
MyException - In case something happen
"""
if True:
raise MyException
return 0
class B(object):
def __init__(self):
self._a = A()
def bar(self):
"""This class does bar
Returns:
Int: number of bar
Raises:
MyException ????? Should this be here?
"""
return self._a.foo()