Pycharm 自动生成文件注解及函数模版

一、自动生成文件注释

1、文件注解

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

pycharm提供了一个在新建文件自动生成文件头注释的功能，可以实现自动生成运行环境，作者、日期等必要信息，使用比较方便，配置十分简单。

模版1：

# -*- encoding: utf-8 -*-
'''
@File    :   ${NAME}.py   
@Contact :   emac.li@cloudminds.com
@License :   (C)Copyright 2018-2021

@Modify Time      @Author    @Version    @Desciption
------------      -------    --------    -----------
${DATE} ${TIME}   Emac.li      1.0         None
'''

模版2：

# -*- coding:utf-8 -*-
#@Time : ${DATE} ${TIME}
#@Author: 陌生初见
#@File : ${NAME}.py
#@Desc:

模版3：

'''
@File  :${NAME}.py
@Author:YangMiao
@Date  :${DATE} ${TIME}
@Desc  :
'''

模版4：

# -*- coding: utf-8 -*-
# @Time    : ${DATE} ${TIME}
# @Author  : 一叶知秋
# @File    : ${NAME}.py
# @Desc  : 

模版5：

#!/usr/bin/env python
# -*- coding: UTF-8 -*-
'''=================================================
@Project -> File   ：${PROJECT_NAME} -> ${NAME}.py
@IDE    ：${PRODUCT_NAME}
@Author ：Mr. Wufei
@Date   ：${DATE} ${TIME}
@Desc   ：
=================================================='''

模版6：

"""
@file: ${FILE_NAME}
@project: ${PROJECT_NAME}
@author: ${USER}
@date: ${DATE}
@description: ${DESCRIPTION}
"""

终极模版：

# -*- coding: utf-8 -*-
"""
@File   : demo_service.py
@Author : kaiyi
@Date   : 2023/5/2 10:06
@Desc   : 
"""

注释设置：

$ {PROJECT_NAME} - 当前项目的名称。
$ {NAME} - 在文件创建过程中在“新建文件”对话框中指定的新文件的名称。
$ {USER} - 当前用户的登录名。
$ {DATE} - 当前的系统日期。
$ {TIME} - 当前系统时间。
$ {YEAR} - 今年。
$ {MONTH} - 当月。
$ {DAY} - 当月的当天。
$ {HOUR} - 目前的小时。
$ {MINUTE} - 当前分钟。
$ {PRODUCT_NAME} - 将在其中创建文件的IDE的名称。
$ {MONTH_NAME_SHORT} - 月份名称的前3个字母。 示例：1月，2月等
$ {MONTH_NAME_FULL} - 一个月的全名。 示例：1月，2月等

二、自定义函数注释模版

Pycharm默认自动生成的函数注释模板

如下图，在pycharm定义函数时，单/双三引号添加函数注释，pycharm会自动帮助生成注释模板。个人觉得不是很美观，用着不习惯。

函数注释模板修改的简单方法

经查阅，该注释模板可以自定义，也有现成的常用注释模板格式供选择。

后来发现直接选择现成注释模板更方便，比如“Google”注释模板格式。相比而言，自定义方法显得繁琐，而且个人觉得没必要花这时间。

以下是选择现成常用注释模板格式的方法：

在pycharm窗口中，依次选择：File→Setting→Tools→Python Integrated Tools→Docstrings→Docstring format: 在下拉菜单中选择“Google” 或是其他你喜欢的格式。

如下图，是Google格式的函数注释模板：

各种风格比较：

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

开启类型占位符注释路径：

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

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

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

相关文章：
pyCharm中添加方法注释（Docstring format & Live Templates）

为者常成，行者常至