【Py】关于Python docstring几种主流风格

123 篇文章 5 订阅

今天在整理Python文档的时候,发现除了目前在用的如下格式外,还有很多种。就简单整理一下。

def foo(bar: str) -> str:
    """
    foo function
    
    :param str bar: bar
    :return: return bar
    :rtype: str
    """
    return bar

目前流行的格式有如下几种,我之前用的属于reST,是目前最广泛的一种方式,是Sphinx原生支持的格式。还有Epytext,好像是从Java那来的。如果你在Swagger Codegen上生成过Python 代码会发现其中的格式也是reST。还有一种比较流行的是Google自家用的格式,貌似更简洁一些,格式可以参考这里。Numpy团队在Google的基础上搞了一套格式,参考这里

Epytext

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

reST

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

Google

"""
This is an example of Google style.

Args:
    param1: This is the first param.
    param2: This is a second param.

Returns:
    This is a description of what is returned.

Raises:
    KeyError: Raises an exception.
"""

Numpydoc

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
    the 1st param name `first`
second :
    the 2nd param
third : {'value', 'other'}, optional
    the 3rd param, by default 'value'

Returns
-------
string
    a value in a string

Raises
------
KeyError
    when a key error
OtherError
    when an other error
"""

参考:
https://stackoverflow.com/a/24385103/7151777

最后,想抱Google的大腿了,但是工作量巨大。。。后悔没在一开始就选好T T

  • 2
    点赞
  • 4
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
Python的文档字符串是在函数、类或模块的开头使用三引号(''')或双引号(""")来编写的注释。文档字符串通常用于解释代码的功能,提供使用示例和参数说明等。谷歌编码风格Python文档字符串有一套特定的规范。 按照谷歌编码风格,文档字符串应该尽量简洁明了,以提供足够的信息供其他人阅读和使用。下面是一些编写文档字符串的基本规范: 1.使用三引号来定义文档字符串,即使用'''或"""包裹文本; 2.文档字符串通常应该以简短的概述开始,介绍函数或类的作用; 3.对于函数,应该描述其输入参数、返回值和可能引发的异常; 4.对于类,应该描述其实例变量和方法,及其作用; 5.使用示例代码来演示函数或类的典型用法; 6.在文档字符串中添加适当的标记,如“Args”(用于描述输入参数)、“Returns”(用于描述返回值)和“Raises”(用于描述引发的异常); 7.使用缩进和空行来提高可读性。 在VS Code中,开发者可以使用Python插件来对文档字符串进行格式化和显示。插件会根据谷歌编码风格的规范,对文档字符串进行格式化并提供高亮显示。这样,开发者可以更轻松地阅读和编辑文档字符串,并清晰地了解代码的功能和使用方式。 总而言之,按照谷歌编码风格的要求,使用规范的格式编写Python的文档字符串,有助于提高代码的可读性和维护性。在VS Code中安装相应的插件可以更方便地编辑和查看文档字符串。
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值