在 Python 中包含文档字符串是干净代码的一部分吗？

Question

我正在做一个项目，我希望我的代码尽可能干净。我想知道在 class 中包含文档字符串是否被认为是干净的代码。比如我的一个class定义如下：

class Hotel:
    """Class to model the rating and rates of a hotel."""

    def __init__(self, rating):
        """
        :type rating: int
        :param rating: hotel rating
        """
        self.rating = rating

我编写代码的方式是否正确，即我是否遵循干净的代码标准。

提前致谢。

Answer 1

整洁的代码在一定程度上是见仁见智的。但我所知道的大多数 Python 支持包括 class 和方法文档字符串。例如，Google Python Style Guide 表示：

A function must have a docstring, unless it meets all of the following criteria:

not externally visible

very short

obvious

...

也就是说，良好的文档字符串不仅仅是拥有它们；一个好的开始是问问自己，如果我以前从未见过它，我需要使用这个 class（或函数）做什么？

在 Python 中包含文档字符串是干净代码的一部分吗？

Is it part of clean code to include docstrings in Python?

python

code-cleanup