几个月前，你写了一段Python代码，当时只有你和上帝能看懂。几个月后，这段代码就只有上帝能看懂了。

痛点是什么

Python是一门弱类型的动态语言，在看其他人写的一些Python项目的代码、特别是大型项目的代码的时候，是不是会有这样的体验：很多函数的参数超多，而且很难看出来每个参数代表什么含义、是什么数据类型的、字典类型的参数究竟可以传哪些参数等等等。如果写这些代码的人习惯还不好，没有写什么注释或注释写的比较糟糕，那看这种代码简直就是一种折磨了，这样的情况下一开篇所描述的情景就并不算夸张了。这样的代码可读性、可维护性几乎为0。

解决方案

PEP 484类型提示语法

那么怎么解决上述痛点呢？Python 3.5版本在语言层面加入了一个新特性：类型提示（Type Hints，详情见开篇引文），可以以一种非常优雅的方式来对代码中变量的类型进行提示，大大提高了Python代码的可读性，例如下面这段代码：

def hello(name:str, age:int) -> str:

return 'hello, {0}! your age is: {1}'.format(name, age)

在IPython中输入这段代码，然后用help函数查看hello函数的帮组文档，显示内容如下：

In [10]: help(hello)

Help on function hello in module __main__:

hello(name: str, age: int) -> str

类型提示语法中，在变量或函数形参后面加:类型名称可以指明变量的数据类型，在函数定义def语句的后面加上-> 类型名称可以指明函数返回值的数据类型，非常方便。

PEP 484类型提示的不足之处

要注意的是，PEP 484的类型提示语言特性只在Python 3.5或更高版本才支持，而且仅仅是作为注释性的语法元素进行解析，在编译的时候类型提示相关的代码都是会被当做注释而忽略掉的，Python编译器并不会因为有了类型提示而对代码做任何类型检查。

更通用的解决方案：文档注释

那么还有没有更好、更通用的办法来解决上述类型提示痛点呢？有的，文档注释就是一个非常好的解决办法。

文档注释的优点

清晰、准确、完善的文档注释可以让Python代码的可读性、可维护性非常高。

不受Python语言版本的限制。

按照一定约定规范书写的文档注释，可以被一些第三方IDE或语法检查工具利用，从而可以对代码做静态类型检查，在语法层面检查代码是否有类型错误，也可以做一些代码补全方面的事情。

PyCharm风格的文档注释

这是一种个人比较推崇的文档注释格式，PyCharm IDE可以识别这种文档注释格式，从而进行代码静态语法类型检查、代码自动补全等操作。

下面是一个简单的示例，在示例中用文档注释标注了hello函数的功能描述、每个形参变量的含义和类型、函数的返回值类型等信息：

def hello(name, age, habits = []):

'''

Say hello to someone, and print some info.

:param name: name of someone

:type name: str

:param age: age of someone

:type age: int

:param habits: habits of someone

:type habits: List[str]

:return: a hello sentence

:rtype: str

'''

return 'Hello, {name}! Your age is {age}, and your habits are {habits}.'.format(name = name, age = age, habits = habits)

将上述代码输入到IPython中，然后执行hello?命令来查看hello函数的文档注释，结果如下：

In [28]: hello?

Signature: hello(name, age, habits=[])

Docstring:

Say hello to someone, and print some info.

:param name: name of someone

:type name: str

:param age: age of someone

:type age: int

:param habits: habits of someone

:type habits: List[str]

:return: a hello sentence

:rtype: str

可以看出函数的功能描述、每个参数的含义和数据类型、函数返回值的含义和数据类型都非常清晰明了。

numpy风格的文档注释

还有一种numpy项目中所使用的文档注释风格，也非常不错，可以参考。一个示例如下：

def squeeze(self, axis=None):

"""

Return a possibly reshaped matrix.

Refer to `numpy.squeeze` for more documentation.

Parameters

----------

axis : None or int or tuple of ints, optional

Selects a subset of the single-dimensional entries in the shape.

If an axis is selected with shape entry greater than one,

an error is raised.

Returns

-------

squeezed : matrix

The matrix, but as a (1, N) matrix if it had shape (N, 1).

See Also

--------

numpy.squeeze : related function

Notes

-----

If `m` has a single column then that column is returned

as the single row of a matrix. Otherwise `m` is returned.

The returned matrix is always either `m` itself or a view into `m`.

Supplying an axis keyword argument will not affect the returned matrix

but it may cause an error to be raised.

Examples

--------

>>> c = np.matrix([[1], [2]])

>>> c

matrix([[1],

[2]])

>>> c.squeeze()

matrix([[1, 2]])

>>> r = c.T

>>> r

matrix([[1, 2]])

>>> r.squeeze()

matrix([[1, 2]])

>>> m = np.matrix([[1, 2], [3, 4]])

>>> m.squeeze()

matrix([[1, 2],

[3, 4]])

"""

return N.ndarray.squeeze(self, axis=axis)

Emacs编辑器自动插入PyCharm风格的文档注释模板

如果你平时经常使用Emacs编辑器写Python代码，那么我写了一个简单的函数，可以方便地在python-mode一键插入上面所讲的PyCharm风格的文档注释。只需将下面的elisp代码加入你的Emacs配置文件中，然后在python-mode写完一个函数的def语句后，光标在def语句所在的行时按快捷键C-c C-a即可快速插入文档注释模板：

(defun insert-doc-annotation-below-current-line ()

"Insert doc annotations for python class or function below current line."

(interactive)

;; first, get current line text

(let ((cur-line-str (buffer-substring-no-properties (line-beginning-position) (line-end-position))))

(cond

;; judge whether current line text match python function define pattern

((string-match "^[[:space:]]*def.+?(\\(.*\\))[[:space:]]*:" cur-line-str)

;; first capture group of regex above is params list string

(setq params-str (match-string 1 cur-line-str))

;; split params list string to list, and do some strip operation

(setq params (split-string params-str ",[[:space:]]*" t "[[:space:]]*=.+?"))

;; go to end of current line and go to new line and indent

(goto-char (line-end-position))

(newline-and-indent)

;; insert head of doc annotation `'''`

(insert "'''")

(goto-char (line-end-position))

(newline-and-indent)

;; record current line number, jump back to here after inserting annotation

(setq annotation-top-line (line-number-at-pos))

(newline-and-indent)

(newline-and-indent)

;; insert each params annotation

(while params

;; NOT insert param `self`

(when (not (string-equal (car params) "self"))

(progn

(setq param (car params))

;; insert param name annotation line

(insert (format ":param %s: " param))

(newline-and-indent)

;; insert param type annotation line

(insert (format ":type %s: " param))

(newline-and-indent)

(newline-and-indent)))

(setq params (cdr params)))

;; insert return and return type annotation line

(insert ":return: ")

(newline-and-indent)

(insert ":rtype:")

(newline-and-indent)

;; insert tail of doc annotation

(insert "'''")

;; jump back to the position of annotation top

(goto-line annotation-top-line)

(indent-for-tab-command))

((string-match "^[[:space:]]*class.+?:" cur-line-str)

(goto-char (line-end-position))

(newline-and-indent)

;; insert head of doc annotation `'''`

(insert "'''")

(goto-char (line-end-position))

(newline-and-indent)

;; record current line number, jump back to here after inserting annotation

(setq annotation-top-line (line-number-at-pos))

(newline-and-indent)

;; insert tail of doc annotation

(insert "'''")

;; jump back to the position of annotation top

(goto-line annotation-top-line)

(indent-for-tab-command))

(t (message "current line NOT match neither function nor class!")))))

(add-hook 'python-mode-hook

(lambda ()

(local-set-key (kbd "C-c C-a") 'insert-doc-annotation-below-current-line)))

总结

最终决定采用文档注释这种更通用的方式在Python代码中做类型提示，虽然无法做到要求其他的人都能为他们自己的Python代码提供完备、清晰的文档注释，但提升代码的可读性可以先从自身做起，起码可以防止那种自己也读不懂自己的代码、只有上帝才能看懂的尴尬局面的发生。