如何写注释

这是知乎上的一个问答:http://www.zhihu.com/question/21114875/answer/18647341

首先 Python 的注释有两种,一种叫 doc string,另一种叫 comment。当我们说注释时,我们两种都要考虑进来。

doc string

def foo():
    """This is an example of foo."""
    return 'foo'

这里我们看到 """This is an example of foo.""" 就是 doc string。doc string 有什么用呢?如果你在 repl 里查看帮助信息的话:

>>> help(foo)

你可以看到这段 doc string 会展示在 help 信息里。如果这个方法使用起来不是显而易见的话,在 doc string 里加上一些例子会更有帮助。

因为 Python 一般使用 sphinx 来生成文档,sphinx 可以提取 doc string 生成 API。那么,好的 doc string 应当能生成足够优秀的 API 文档。这里我拿自己的一个库举个例子:Developer Interface

对于 Python,你需要了解 reStructuredText 语法,你写 doc string 时也需要用到。

comment

def foo():
    # python 3 has no iteritems
    if hasattr(d, 'iteritems'):
        return d.iteritems()
    return d.items()

这里我们看到 # python 3 has no iteritems 就是 comment,comment 不应该滥用,一些显而易见的地方写一堆 comment 是没有意义的。comment 的用处应该是便于你去理解为何要这样写,如果你的代码足够清晰易懂,comment 是没有必要的。

总结:doc string 是站在使用者的角度,告诉别人怎么用;comment 是站在开发者的角度,告诉别人为何这样写。

附:多看优秀的代码,学习别人的代码。比如 Flask。

我一直认为 Python 有最好的文档体系,这一点是其它语言都缺乏的,比起其它语言,写 python 的文档是件非常愉快的事。 Python 的 doc string 设计真是方便生成 API 文档,而 sphinx 可以说是第一好用的文档生成工具。

拓展阅读:

  1. http://www.python.org/dev/peps/pep-0257/ 请忽略其中 parameters 的例子
  2. http://www.python.org/dev/peps/pep-0287/ doc string 请使用 rst 格式
4 comments