我尝试使用活动和描述性的函数名称，然后我用活动和描述性文本 (!) 记录这些名称。这会生成看起来多余的代码。
python中的简化（但不是那么不切实际）示例，遵循numpy docstring样式：
def calculate_inverse(matrix):
"""Calculate the inverse of a matrix.
Parameters
----------
matrix : ndarray
The matrix to be inverted.
Returns
-------
matrix_inv : ndarray
The inverse of the matrix.
"""
matrix_inv = scipy.linalg.inv(matrix)
return matrix_inv
特别是对于 python，我已经阅读了PEP-257和 sphinx/napoleon 示例numpy和 Google 风格的文档字符串。我喜欢我可以为我的函数自动生成文档，但是对于像上面这样的冗余示例，“最佳实践”是什么？是否应该简单地不记录“明显”的类、函数等？“显而易见”的程度当然变得主观......
我想到了开源的分布式代码。多个作者建议代码本身应该是可读的（calculate_inverse(A)比 更好dgetri(A)），但多个最终用户将从 sphinx 样式的文档中受益。