python 代码注释

阿里云国内75折回扣微信号：monov8

阿里云国际，腾讯云国际，低至75折。AWS 93折免费开户实名账号代冲值优惠多多微信号：monov8 飞机：@monov6

文章目录

写在前面

如果说高效率的算法是一个项目的内核那么完备的文档注释、API 接口则是项目的外壳直接与客户交互。
pycharm 提供了 5 种代码注释格式。
分别是 plain, epytext, google, numpy, reStructuredText

使用方法

在 file / setting / tools / python integrated tools / docstrings
在这里插入图片描述

在这里插入图片描述
使用 ctrl+q 可以查看某函数的注释

plain

这种模式适合简单的注释不涉及参数、返回值之类的简单的几句话即可

def test_plain(a: str, b: int):
    """
    Nothing
    """

Epytext

这种格式源自 java 语言官方文档。
该格式是一种轻量级的注释方法使用简单适合较小的文档但通用性较差。

代码样式

def test_epytext(a: str, b: int):
    """
    AAA

    @param a: AA
    @type a: str
    @param b: BB
    @return: CC
    @rtype: str
    """

其中@后的注释块被叫做 filed不同的 filed 有着不同的含义
下表是部分官方介绍
在这里插入图片描述
上述代码段在 pycharm 中查看如下

Google

这是一款使用较广泛的格式示例代码如下

def test_google(a: str, b: int):
    """summary

    Nothing

    Args:
        a (str): hhhh
        b (int): bbbb

    Returns:
        str: nono

    """

使用 pycharm 查看如下
在这里插入图片描述

Numpy

这也是一款使用广泛的格式如下

def test_numpy(a, b):
    """summary

    AAA

    Parameters
    ----------
    a : str
        input
    b : int
        input

    Returns
    -------
    c : str
        nono

    """

在pycharm中显示如下

在这里插入图片描述

reStructuredText

这款格式适配 sphinx 等网页文档较好是 pycharm 默认的格式。但我个人感觉可读性较差
示例代码

def test_reStructuredText(a: str):
    """summary
    
    Test hhhh

    :param a: para
    :type a: str
    :return: Nothing
    :rtype: str
    """

pycharm 中查看渲染
在这里插入图片描述