浅谈Python注释

浅谈Python注释

写代码+注释就像是程序员的礼仪，能够有利于程序交流的简便。当看到密密麻麻的代码的时候，向我们这样的小白最希望看到的就是注释了，简单方便易懂。所以，有必要了解一下python的注释及规范。

part1 python的注释类型

python中增加注解的操作主要就是两个：__1__单行注解(以#号为注释头)，__2__多行注解(以”“”为注释头)。不过，随着python版本的更新，注释的使用越来越多样了，这在后面会一一介绍。

单行注解

通常，是用来在代码中阐述自己在对该行进行的操作内容。例如，参数说明，数据处理说明，以及对象说明等等，你可以在#号后面添加任意你想要添加的内容，表达你的注释。

pycharm 快捷键：对选中内容 + Ctrl/Command +/

（后期如有pycharm相关博客，会及时贴出来）

#参数说明
num = 1     #创建一个num的int参数-用来记录****

#操作说明
num += 1    #对num进行自加1操作

#或者随意的添加你想要表达的意思or表情🎆🎨

在python3.5之后，新增了：的注释方式来对一些参数更方便的增加类型注释。一般只能用来说明参数属于什么类型，但python对这种类型的注释没有强制性，即使你对参数的操作不属于注释类型，python也并不会报错。

num : int = 1  #向编译器说明num的参数为int型

num : int = [2.3]  #并不会由错误提示

num : "any thing you want 🎋" = 1 #冒号后也可以添加字符串

这种方法的注释好处就是可以为你提供类型的原有函数

例如上图，你可以利用string类型为自己提供函数提示，即使a不属于字符串

多行注释

多行注释，其实就是单行注释的plus版本。多因为需要注释的内容多于一行，因为采用多行注释不需要每行重复操作。三个单引号与三个多引号均可实现多行注释。

'''
	单引号注释
'''
“”“
	多引号注释
”“”

part2 python中的常用注释

文件注释

文件注释，属于特殊注释中的一种，指的是每个python文件开头的注释内容，如下所示。

#!./use/bin/env python
# -*- coding: utf-8 -*-
# Python version: 3.6
# @DATE $$-$$-$$

文件注释，通常用来对文件内容，版本，性质等属性，按照自己的需求进行注释说明。一般前两行是通用格式，下面来逐一讲解。

#!./usr/bin/env python

这句注释的作用是，引导LINUX/UNIX系统找到相关的python处理器，运行该文件。但是，提示：该句注释在windows系统内不生效，如果想要该注释凑效，可以使用Git bash。windows内可以直接通过指定对应文件后缀名的默认应用程序，来通知系统。

扩展：这句注释有两个部分组成：1.#! _(它的名字是``Shebang或者Sha-bang`，通常出现在系统的脚本中第一行，作为前两个字符。在Shebang之后，可以有一个或数个空白字符，后接解释器的绝对路径，用于指明执行这个脚本文件的解释器。)，2./usr/bin/python 或者 /usr/bin/env python。

其中的一些区别可以参考[#!/usr/bin/env python 有什么用？]。

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

这句注释向python的编译器解释了字符串的编码方式，如果使用中文，你必须使用它。

文件注释的其余部分可以写上关于这个模块即这个Python文件实现的功能一些注意点，可能会发生的错误，总之你得注释要让使用它的人很明白你的文件。

函数注释

def func(num:int) -> "返回类型":
    """
    一些函数作用的说明
    :param num: 
    :return: int     
    """
    
    num += 1  # 一些必要的地方增加注释
    
    return num

如上所示，每一个函数在内部都可以添加多行注释以及单行注释，注释的目的是为了说明函数的入参，出参，作用等。因此，一般来说，每一个函数下面会加上多行注释，说明整体结构。另外，也会在必要的地方加上单行注释-提醒自己或者别人注意的代码、重要代码。

tips 1 函数的入参、出参的注释在pyhton3.5之后，可以利用：以及->在函数申明处表示。两者除了 表达内容的篇幅不同，以外还涉及到了函数的__doc__字段。如下，在函数申明处属于__annotation__字段，在函数体内属于__doc__字段。

tips 2 pycharm中可以直接利用Ctrl/Command+q，快速查看注释。

part3 python注释风格

1.reStructuredText（PyCharm默认）— pychram内，函数使用多行注释会自动生成

def func(path):
    '''
    基本描述
    详细描述

    :param path: 参数介绍
    :type path: 参数类型介绍
    :returns: 返回参数介绍
    :rtype: 返回参数类型介绍
    另外还有：exception等等，可以参考官网介绍
    '''
    pass

2.NumPy

def func(path):
    '''
    基本描述
    详细描述
    
    Parameters
    ----------
       	--入参说明
    Returns
    -------
		--出参说明
    '''
    pass

3.Google（官方推荐）

def func(path, field_storage, temporary):
    '''
    基本描述
    详细描述

    Args:
        --入参说明
    Returns:
       	--出参说明
    '''
    pass

风格	特点	适用
reStructuredText	用冒号分隔	PyCharm默认
NumPy	用下划线分隔	倾向垂直，长而深的文档
Google	用缩进分隔	倾向水平，短而简单的文档

更多关于注释的相关信息，可以参考[ Google 开源项目风格指南](https://zh-google-styleguide.readthedocs.io/en/latest/google-python-styleguide/python_style_rules/#comments)

参考

Python里的一些注释规范

[#!/usr/bin/env python 有什么用？]

Python类和方法注释规范