西双版纳州住房和城乡建设局网站,织梦动漫网站模版,织梦手机wap网站标签调用,牛商网股票代码几个月前#xff0c;你写了一段Python代码#xff0c;当时只有你和上帝能看懂。几个月后#xff0c;这段代码就只有上帝能看懂了。
痛点是什么
Python是一门弱类型的动态语言#xff0c;在看其他人写的一些Python项目的代码、特别是大型项目的代码的时候#xff0c;是不是…几个月前你写了一段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: strreturn 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, axisNone):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.Tr
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, axisaxis)
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代码提供完备、清晰的文档注释但提升代码的可读性可以先从自身做起起码可以防止那种自己也读不懂自己的代码、只有上帝才能看懂的尴尬局面的发生。
