如果在代码中处理错误，Docstring 是否应该包含 'Raises' 语句

Question

假设我有一个简单的函数。例如：

def if_a_float(string):
   try:
       float(string)
   except ValueError:
       return False
   else:
       return True

我应该将 Raises: ValueError 语句包含到我的文档字符串中，还是应该避免它，因为代码中已经处理了错误？是否因任何错误（caught/uncaught）而完成？我知道这可能取决于样式，所以假设我使用的是 Google Docstring style（尽管我想这没那么重要）

Answer 1

您应该根据 Google Style Guidelines（您自己提到的同一文档）记录明确提出的异常以及可能与接口相关的异常。

此代码不会显式引发异常（没有 raise），您无需提及您正在捕获异常。实际上，这段代码甚至不会意外地引发一个（你正在捕获唯一可能的行）因此如果你要记录 if_a_float() 正在引发 ValueError.[=14= 将会产生误导]

Answer 2

您应该只记录调用者需要注意并可能想要捕获的异常。如果函数本身捕获了异常并且没有将其引发给调用者，则它是调用者不需要知道的内部实现细节，因此不需要记录。

Should Docstring contain a 'Raises' statement if the error is handled in the code