我所理解的python函数注释规范

关于函数说明的注释

首先来两段优秀开源框架的代码注释
例1 tornado.web.RequestHandler的get_arguments函数.

 def get_argument(self, name, default=_ARG_DEFAULT, strip=True):
        """Returns the value of the argument with the given name.

        If default is not provided, the argument is considered to be
        required, and we raise a `MissingArgumentError` if it is missing.

        If the argument appears in the url more than once, we return the
        last value.

        The returned value is always unicode.
        """
        return self._get_argument(name, default, self.request.arguments, strip)

例2 requests的get函数

def get(url, params=None, **kwargs):
    """Sends a GET request.

    :param url: URL for the new :class:`Request` object.
    :param params: (optional) Dictionary or bytes to be sent in the query string for the :class:`Request`.
    :param \*\*kwargs: Optional arguments that ``request`` takes.
    :return: :class:`Response ` object
    :rtype: requests.Response
    """

    kwargs.setdefault('allow_redirects', True)
    return request('get', url, params=params, **kwargs)

对比下例1和例2, tornado框架的函数倾向与给出函数的用途说明，而不提供具体的输入参数说明，并且相对来说函数名字也是浅显易懂，而requests库看起来比较简洁一点，具体的输入和输出都给的很完整，看起来很是赏心悦目，所以我个人更偏向于例2的注释，当然，也有将例1和例2注释特点结合起来的库，比如tensorflow库，因为涉及的输入参数以及函数较为复杂，因此输入参数和函数原理有较为详尽的说明。总之，大部分编写函数的时候参考例2的注释方式，代码也看起来较为优雅，而遇到比较复杂的情况，则可以参考例1加上必要的函数详细说明。