pyCharm中添加⽅法注释（DocstringformatLiveTemplates）版权声明：本⽂为原创⽂章，未经博主允许不得转载。
优雅规范的注释有助于对代码理解，易于与⼈合作开发，提⾼效率。但若没有⾃动化的注释会让写注释耗时耗⼒。
注释中的要素包括：功能和⽤途简介、参数、返回值、创建⼈、创建时间、修改⼈、修改时间、版权声明、异常抛出。
本⽂介绍在 pyCharm 中使⽤两种⽅式进⾏⽅法的注释：Docstring format 和 Live Templates。
1 Docstring format
1.1 Docstring format 添加⽅法注释
Docstring format 可通过下⽅路径进⾏设置，包括五种风格：Plain、Epytext、reStructuredText、Numpy、Google。
File -> Settings -> Tools -> Python Integrated Tools -> Docstrings -> Docstring format
使⽤⽅式为，在⽅法名下⽅输⼊三个双（单）引号，回车，⾃动⽣成。五种风格的样式如下：
def docstrings_func_plain(parm_a, parm_b, parm_c):
"""
Plain 风格
"""
def docstrings_func_epytext(parm_a, parm_b, parm_c):
"""
Epytext 风格
@param parm_a: 参数a
@param parm_b: 参数b
@param parm_c: 参数c
@return: 结果a
"""
def docstrings_func_restructuredtext(parm_a, parm_b, parm_c):
"""
reStructuredText 风格
:param parm_a: 参数a
:param parm_b: 参数b
:param parm_c: 参数c
:return: 结果a
"""
def docstrings_func_numpy(parm_a, parm_b, parm_c):
"""
NumPy 风格
Parameters
----------
parm_a : 参数a
parm_b : 参数b
parm_c : 参数a
Returns
-------
result_a : 结果a
"""
def docstrings_func_google(parm_a, parm_b, parm_c):
"""
Google 风格
Args:
parm_a: 参数a
parm_b: 参数b
parm_c: 参数c
Returns:
result_a  结果a
"""
1.2 Docstring format 添加参数类型注释
Python是动态语⾔，使⽤动态类型（Dynamic Typed），即在运⾏时确定数据类型，变量使⽤之前不需要类型声明；对于⼀些已经确定类型的参数，加上类型的注释，可以借助pyCharm的⽅法类型检查功能，在书写代码时就能够提前发现错误。
下⾯代码第⼀⾏是没加参数类型注释，第⼆⾏添加了参数类型注释，pyCharm就可根据⽅法对应的docstrings提前判断输⼊参数类型的问题，并给出正确类型提⽰。
pyCharm中开启插⼊类型占位符注释路径如下：
File -> Settings -> Editor -> General -> Smart Keys -> Insert type placeholders in the documentation comment stub
开启后再使⽤ Docstring format 添加⽅法注释，就会出现类型占位符。
对于reStructuredText风格，可将参数类型与参数描述同⼀⾏，也可分开书写。
格式化（可通过快捷键查看 Ctrl + Q）的Epytext注释如下：
添加了参数类型的各⽅法注释如下：
def docstrings_func_epytext_type(parm_a, parm_b, parm_c):
"""
Epytext 风格 - 参数类型
@param parm_a: 参数a
@type parm_a: int
@param parm_b: 参数b
@type parm_b: str
@param parm_c: 参数c
@type parm_c: bool
@return: result_a 结果a
@rtype: int
"""
def docstrings_func_restructuredtext_type(parm_a, parm_b, parm_c): """
reStructuredText 风格 - 参数类型
:param parm_a: 参数a
:type parm_a: int
:param parm_b: 参数b
:type parm_b: str
:
param parm_c: 参数c
:type parm_c: bool
:return: result_a 结果a
:rtype: int
"""
def docstrings_func_restructuredtext_type_2(parm_a, parm_b, parm_c): """
reStructuredText 风格 - 参数类型与参数描述同⼀⾏
:param int parm_a: 参数a
:param str parm_b: 参数b
:param bool parm_c: 参数c
:return: result_a 结果a
:
rtype: int
"""
def docstrings_func_numpy_type(parm_a, parm_b, parm_c):
"""
NumPy 风格 - 参数类型
Parameters
----------
parm_a : int
参数a
parm_b : str
参数b
parm_c : bool
参数c
Returns
-------
result_a : int
结果a
"""
def docstrings_func_google_type(parm_a, parm_b, parm_c):
"""pycharm安装教程和使用
Google 风格 - 参数类型
Args:
parm_a (int): 参数a
parm_b (str): 参数b
parm_c (bool): 参数c
Returns:
result_a (int):  结果a
"""
2 Live Templates
Docstring format 已经可以⾃动格式化输出docstrings，但⽆法加上创建⼈、创建时间、修改⼈、修改时间、版权声明；有些规范建义这些元素写在⽂件头部，⽽对于协同开发同⼀⽂件，觉得还是需要把这些元素加在各个⽅法⾥⾯，会更清晰明了。
可通过pyCharm的 Live Templates ⾃定义模板实现。
Live Templates中设置路径如下：
File -> Settings -> Editor -> Live Templates
添加⽅式如下：
1. 进⼊ Live Templates 设置页⾯，点击右⽅加号，添加 Template Group，再添加 Live Template
2. 在下⽅添加 Abbreviation（快捷键缩写），Desctiption （快捷键描述）

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。