3.Python代码质量

为什么需要记录Python代码?项目文档应该包括什么?如何编写和生成文档?

文档是软件开发的重要组成部分。 如果没有适当的文档,内部和外部利益相关者可能很难或不可能使用或维护我们的代码。这也使得新加入的开发人员变得更加困难。甚至自己也看不懂自己写下的代码。

1 注释 vs 文档

文档是一个独立的资源,可以帮助其他人使用我们的API、程序包、库或框架等,而无需阅读源代码。而注释是供阅读源代码的开发人员使用的。 文档应该告诉其他人:

  1. 什么时候用
  2. 怎么用

而注释应该告诉其他人:

  1. 这是啥?
  2. 这个函数做了什么?
  3. 为什么这样做?等。

2 Docstrings

Python的docstring是一种特殊的字符串,它作为模块、函数、类或方法定义中的第一条语句出现,形成给定对象的__doc__属性。 它使您可以将文档直接嵌入到源代码中:

"""
The temperature module: Manipulate your temperature easily

Easily calculate daily average temperature
"""


from typing import List


class HighTemperature:
    """Class representing very high temperatures"""

    def __init__(self, value: float):
        """
        :param value: value of temperature
        """


        self.value = value


def daily_average(temperatures: List[float]) -> float:
    """
    Get average daily temperature

    Calculate average temperature from multiple measurements

    :param temperatures: list of temperatures
    :return: average temperature
    """


    return sum(temperatures) / len(temperatures)

我们可以看到daily_average__doc属性:

>>> from temperature import daily_average
>>>
>>> print(daily_average.__doc__)

    Get average daily temperature

    :param temperatures: list of temperatures
    :return: average temperature

我们可以用内置的help查看更详细的信息:

>>> import temperature
>>>
>>> help(temperature)

我们可以通过docstrings指定:

  1. 函数参数
  2. 函数返回
  3. 类属性
  4. 异常
  5. 边界或限制
  6. 示例代码等

比较流行的文档风格:

  1. Google[1]
  2. reStructuredText[2]
  3. Numpy[3]
  4. Epytext[4]

选择一种适合自己的文档风格,或者自定义一种属于自己的风格,使我们的项目更清晰。

参考资料

[1]

Google: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings

[2]

reStructuredText: https://docutils.sourceforge.io/rst.html

[3]

Numpy: https://numpydoc.readthedocs.io/en/latest/format.html

[4]

Epytext: http://epydoc.sourceforge.net/epytext.html

 wechat
您的支持将鼓励我继续创作!
您的支持将鼓励我继续创作!
--------------本文结束,感谢您的阅读--------------