版权声明：本文为博主原创文章，未经博主允许不得转载。
优雅规范的注释有助于对代码理解，易于与人合作开发，提高效率。但若没有自动化的注释会让写注释耗时耗力。
注释中的要素包括：功能和用途简介、参数、返回值、创建人、创建时间、修改人、修改时间、版权声明、异常抛出。
本文介绍在 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注释如下：
添加了参数类型的各方法注释如下：
Docstring format 已经可以自动格式化输出docstrings，但无法加上创建人、创建时间、修改人、修改时间、版权声明；有些规范建义这些元素写在文件头部，而对于协同开发同一文件，觉得还是需要把这些元素加在各个方法里面，会更清晰明了。
可通过pyCharm的 Live Templates 自定义模板实现。
Live Templates中设置路径如下：
File -> Settings -> Editor -> Live Templates
添加方式如下：
进入 Live Templates 设置页面，点击右方加号，添加 Template Group，再添加 Live Template在下方添加 Abbreviation（快捷键缩写），Desctiption （快捷键描述）
3. 在下方添加 Applicable（可应用的语言范围）
4. 在 Template text 中添加下方模板代码
5.在 Edit variables 中配置 DATE 和 TIME，使创建时间自动生成
6. 为了使用注释方便，还可添加 更新时间 和 当前时间
7. 在方法下方输入配置的 Abbreviation，使用 Tab 或 回车 都可自动生成注释，见下方代码
使用 Live Templates 添加方法注释有个问题，方法参数无法自动生成，需要从 Docstring format 方法注释复制。因暂未找到 Live Templates 中解析方法参数的pyCharm内置方法；如 IDEA 中解析方法参数的内置方法 methodName()，解析方法返回参数类型的内置方法 methodReturnType()，methodName() 结合 groovyScript(“def result=’’; def params=”${_1}".replaceAll(’[\[|\]|\s]’, ‘’).split(’,’).toList(); for(i = 0; i < params.size(); i++) {result+=’ * @param ’ + params[i] + ((i < params.size() - 1) ? ‘n’ : ‘’)}; return result", methodParameters())，可实现在 Live Templates 中解析方法参数并按格式输出。
不知是否是因为pyCharm支持了标准的 Docstring format 而没有设置该方法，找了很长时间都没找到解决方案，期待各大神不吝赐教。
注释代码如下：
def docstrings_func_live_templates(parm_a, parm_b, parm_c): """ Live Templates 自定义 Parameters ---------- Returns ------- :Author: dkjkls :Create: 2019/3/31 16:55 :Blog: https://blog.csdn.net/dkjkls Copyright (c) 2019, dkjkls Group All Rights Reserved. """def docstrings_func_live_templates_parm_type(parm_a, parm_b, parm_c): """ Live Templates 自定义 参数从docstrings_func_restructuredtext复制，暂未找到live_templates中解析方法参数的pyCharm内置方法 IDEA 解析方法参数的内置方法 methodName(), 解析方法返回参数类型的内置方法 methodReturnType() methodName() 结合 groovyScript("def result=''; def params=; return result", methodParameters())，可实现在live_templates中解析方法参数并按格式输出 Parameters ---------- :param int parm_a: 参数a :param str parm_b: 参数b :param bool parm_c: 参数c Returns ------- :return: result_a 结果a :rtype: int :Author: dkjkls :Create: 2019/3/31 16:55 :Blog: https://blog.csdn.net/dkjkls Copyright (c) 2019, dkjkls Group All Rights Reserved. """ 参考：https://www.jetbrains.com/help/pycharm/using-docstrings-to-specify-types.html
https://www.jetbrains.com/help/pycharm/settings-smart-keys.html
--------------------------文档信息--------------------------
版权声明：本文为博主原创文章，未经博主允许不得转载
署名(BY) ：dkjkls（dkj卡洛斯）
文章出处：http://blog.csdn.net/dkjkls