pycharm文件头规范和函数注释自动生成

优雅规范的注释有助于对代码理解，易于与人合作开发，提高效率。但若没有自动化的注释会让写注释耗时耗力。可以自动生成功能和用途简介、参数、返回值、创建人、创建时间、修改人、修改时间、版权声明、异常抛出。

下面介绍在 pyCharm中使用两种方式的注释：

1. 文件头规范自动生成

在文件头加上创建人、创建时间、修改人、修改时间、版权声明；有些规范建义这些元素写在文件头部。可通过如下方法设置：

File->Settings->Editor->File and Code Templates->Python Script

# -*- coding: utf-8 -*-

"""
@Time    : 2022/5/24 11:26 下午
@Author  : hanscal
@Email   : hanscal@xxx.com
"""

2.函数注释自动生成

Docstring format 添加方法注释

File | Settings | Tools | Python Integrated Tools | Docstring format | reStructuredText

包括五种风格包括五种风格：Plain、Epytext、reStructuredText、Numpy、Google。此处如果是 plain 就导致定义函数之后不能自动生成注释。

使用方式为，在方法名下方输入三个双（单）引号，回车，自动生成。

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
    """

Docstring format 添加参数类型注释

Python是动态语言，使用动态类型（Dynamic Typed），即在运行时确定数据类型，变量使用之前不需要类型声明；对于一些已经确定类型的参数，加上类型的注释，可以借助pyCharm的方法类型检查功能，在书写代码时就能够提前发现错误。

pyCharm中开启插入类型占位符注释路径如下：

File -> Settings -> Editor -> General -> Smart Keys -> Insert type placeholders in the documentation comment stub

开启后再使用 Docstring format 添加方法注释，就会出现类型占位符。

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):
    """
    Google 风格 - 参数类型

    Args:
        parm_a (int): 参数a
        parm_b (str): 参数b
        parm_c (bool): 参数c

    Returns:
        result_a (int):  结果a
    """