Python注释风格

近日看了下requestsflask源码,很多人都觉得,看源码很难,确实,但是首先,你得告诉自己,我为什么看源码。平时我在用django的时候,有一些地方觉得文档说得不够细,我也看一下源码,看看接口需要哪些参数,参数的作用等等。所以,看源码不一定为了看懂整一个模块的所有的,逻辑等等,我这次看requestsflask的源码,就是看一下文件结构、代码风格以及注释怎么写,这里主要说说注释的写法吧。

这个写法其实也是按个人风格而言,我只是觉得requestsflask这个两个模块的注释,看着舒服,所以推荐下。

文件注释

与文件头(# -*- coding: utf-8 -*-)隔开一行,内容使用"""注释,第一行是文件绝对路径名,如果是包的根目录,则可以写包标题,接着是~~~~~~~~作为分隔。接着是文件详细说明或者用法等,上下有分隔行,最后是copyright,license,或者作者信息等等。下面是例子:

"""
requests.api                                                                                                                                                                                                      ~~~~~~~~~~~~

This module implements the Requests API.

:copyright: (c) 2012 by Kenneth Reitz.
:license: Apache2, see LICENSE for more details.
"""
"""
Requests HTTP library
~~~~~~~~~~~~~~~~~~~~~

Requests is an HTTP library, written in Python, for human beings. Basic GET
usage::
  >>> import requests
  >>> r = requests.get('https://www.python.org')
  >>> r.status_code
  ...

:copyright: (c) 2016 by Kenneth Reitz.
:license: Apache 2.0, see LICENSE for more details.
"""

PS: 注意最后的copyright等写法,前后有两个:flask模块的文件注释内容,会向后扩展4个空格,我觉得没必要,个人推荐requests这种。

类/方法注释

  1. 使用"""注释,注释和代码分隔一行,在第一个"""那一行开始写注释内容。
  2. 参数说明则分隔一行,参数注释格式为:param 参数名: 注释内容
  3. 注释某个参数的类型,则在对应param下一行写上注释内容,格式为:type 参数名: 内容
  4. 注释某个变量的class,在变量后面加上:class:
  5. 注释返回什么,可以用:return:表示,返回的类型则用:rtype:表示
  6. 一行过长,可以换行写,但需要缩进(4个空格),其它的例如usage::之后可以两个空格,为了避免缩紧太多
  7. 注释的详细说明和第一行的标题说明分隔一行
  8. 如果对非参数和返回的信息进行说明,例如版本,则使用.. versionchange::,或者是其它特殊说明

例子如下:

def patch(url, data=None, **kwargs):
    """Sends a PATCH request.

    :param url: URL for the new :class:`Request` object.
    :param data: (optional) Dictionary, bytes, or file-like object to send in the body of the :class:`Request`.
    :param \*\*kwargs: Optional arguments that ``request`` takes.
    :return: :class:`Response <Response>` object
    :rtype: requests.Response
    """

    return request('patch', url, data=data, **kwargs)

行注释

一般对于一个变量做注释的话,使用#:,其它行注释则使用#,一行不能说明,就多行

例如:

#: Default Authentication tuple or object to attach to
#: :class:`Request <Request>`.
self.auth = None

...

# Send the request.
send_kwargs = {
    'timeout': timeout,
    'allow_redirects': allow_redirects,
}
send_kwargs.update(settings)
resp = self.send(prep, **send_kwargs)

return resp