Python注释的使用方法（详解）

本文的目录：

零、时光宝盒

一、注释规则

二、单行注释

1.1、单行注释第一种形式

1.2、单行注释第二种形式

三、多行注释（块注释）

3.1、多行注释第一种形式

3.2、多行注释第二种形式

四、中文注释

五、拓展说明

5.1、嵌套结构

5.2、函数的注释

五、放松一下，一起来欣赏一下大能们有趣的注释（转自网络）

---

  零、时光宝盒

　　如果家里的小孩或认识的人常常感觉冷，或者突然感觉很热，直冒汗，爱睡觉或睡觉时间过长，有异常感觉，类似感觉被鬼弄，听到有异常的说话声音但看不到人，哭泣，跟你们倾诉这些异常但你们不相信他（她），自言自语，睡觉抽筋，害怕锁门，情绪波动大等等异常情况，请不要随便因为自己不能理解或旁人的闲话轻易就判定她们疯了。

　　她们这种状况不是疯了，也不是得什么奇怪的病导致，你们理解不了，但事实上她们正经历一些常人无法理解的事情，不是被真鬼弄，是被坏人通过高科技手段欺负！你们帮不了也请相信她们，将健康人当疯子对待治疗是很残忍的事情。如果你们没有在身边守护陪伴安慰，她们真的很有可能被坏人逼疯。

　　家人的理解和陪伴是她们度过难关，不发生无法挽回意外的关键。

　　成年人也会发生同样事情，请理解守护好自己的家人，守护好你们的朋友。不要把那些可怜无助的人当笑话般嘲笑，如果你们遇到同等的事情，表现未必如她们。

     逆境清醒

2024.8.21

一、注释规则

　　在 Python3 中，注释不会影响程序的执行，但是会使代码更易于阅读和理解。

　　在Python中，通常包括3种类型的注释，分别是单行注释、多行注释和中文注释。

　　注释可以出现在代码的任意位置，但是不能分隔关键字和标识符。

　　很多时候，在IDLE开发环境中，可以通过菜单中的Format→Comment Out Region选项，或者UnComment Region选项，将选中的代码注释掉，取消添加的单行注释。

Comments 注释规范：

• 与代码相矛盾的注释比没有注释还糟，当代码更改时，优先更新对应的注释！
• 注释应该是完整的句子。如果一个注释是一个短语或句子，它的第一个单词应该大写，除非它是以小写字母开头的标识符(永远不要改变标识符的大小写！)。
• 如果注释很短，结尾的句号可以省略。块注释一般由完整句子的一个或多个段落组成，并且每句话结束有个句号。
• 在句尾结束的时候应该使用两个空格。
• 当用英文书写时，遵循Strunk and White （译注：《Strunk and White, The Elements of Style》）的书写风格。
• 在非英语国家的Python程序员，请使用英文写注释，除非你120%的确信你的代码不会被使用其他语言的人阅读。

PEP 8中，对python注释规范如下：

　　与代码相矛盾的注释比没有注释更糟糕。当代码发生变化时，始终优先保持注释的最新状态！
评论应该是完整的句子。第一个单词应该大写，除非它是一个以小写字母开头的标识符（永远不要改变标识符的大小写！）。
　　阻止评论通常由一个或多个由完整句子构建的段落组成，每个句子以句号结尾。
　　在多句评论中，除了最后一句之后，你应该在句末句号后使用一两个空格。
　　确保你的评论清晰明了，易于其他使用你所写语言的人理解。
　　来自非英语国家的Python程序员：请用英语写你的评论，除非你有120%的把握，不说你语言的人永远不会读到你的代码。

　　块注释通常应用于后面的一些（或所有）代码，并缩进到与该代码相同的级别。块注释的每一行都以#和一个空格开头（除非注释内是缩进文本）。
　　块注释内的段落由包含单个#的行分隔。
　　行内注释
　　谨慎使用内联注释。
　　内联注释是与语句位于同一行的注释。内联注释应与语句至少隔开两个空格。它们应该以一个#和一个空格开头。
　　内联注释是不必要的，如果它们陈述了显而易见的内容，实际上会分散注意力。不要这样做：

x=x+1#增量x

但有时，这是有用的：

x=x+1#边界补偿

二、单行注释

　　单行注释：

　　在Python中，单行注释以"#"符号开头，后面跟随要注释的文字。在代码中的一行中使用#符号来添加单行注释。#后的内容都作为注释的内容而被Python编译器忽略，并不会在执行结果中体现出来。

单行注释使用方法：

# 注释内容

　　单行注释可以放在要注释代码的前一行，也可以放在要注释代码的右侧。

Inline Comments 行内注释：

• 有节制地使用行内注释。
• 行内注释是与代码语句同行的注释。行内注释和代码至少要有两个空格分隔。
• 注释由#和一个空格开始。

　　下面的两种注释形式都是正确的。

1.1、单行注释第一种形式

单行注释第一种形式，放在要注释代码的前一行。

如果单行文字采用#开头，其后就是注释内容。一般采用这种注释来描述此后一段程序的功能。

print("逆境清醒——从0开始学python__注释");
# 被泼过太冷的雨滴和雪花，更坚持微笑要暖得像太阳
print("#")
'
运行
运行

输出结果：

逆境清醒——从0开始学python__注释
#

print("逆境清醒——从0开始学python__注释")
 
# 输入要求：身高输入单位为m（米），保留2位小数。如1.80
xb=input("请输入您的性别：")
height=float(input("请输入您的性别和身高："))
print(xb,height)

输出结果：

1.2、单行注释第二种形式

单行注释第二种形式，放在要注释代码的右侧。

采用#开头，并写在一行语句或表达式的后面的注释，一般用来说明该行语句或表达式的作用。

print("逆境清醒——从0开始学python__注释")
​​​​​​​xb=input("请输入您的性别：")
height=float(input("请输入您的性别和身高："))# 输入要求：身高输入单位为m（米），保留2位小数。如1.80
print(xb,height)

输出结果：

注释可以出现在代码的任意位置，但是不能分隔关键字和标识符。

　　例如，下面的代码注释是错误的：

　　height=float(#按要求的格式输入体重值 input("请输入您的体重值："))

 

三、多行注释（块注释）

　　在Python中，并没有一个单独的多行注释标记，而是将包含在一对三引号（'''……'''）或者（"""……"""）之间，并且不属于任何语句的内容认为是注释。对于这样的代码，解释器将忽略。由于这样的代码可以分为多行编写，所以也作为多行注释。

　　多行注释以三个引号（'''）或三个双引号（"""）开始和结束，可以注释多行文字。

　　多行注释通常用来为Python文件、模块、类或者函数等添加版权、功能修改日志等信息。例如：

'''
@ 版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。     
博主链接：https://blog.csdn.net/weixin_69553582/
版权所有：逆境清醒
修改时间：2024年8月21日
 '''

多行注释（块注释）语法格式如下：

    '''
        注释内容1
        注释内容2
        ……
    '''

或者
    """
        注释内容1
        注释内容2
        ……
    """

Block Comments 块注释（多行注释）：

• 块注释通常适用于跟随它们的某些（或全部）代码，并缩进到与代码相同的级别。
• 块注释的每一行开头使用一个#和一个空格（除非块注释内部缩进文本）。
• 块注释内部的段落通过只有一个#的空行分隔。
• 块注释（即多行注释），一般用于注释内容较多的情形。虽然块注释也可采用多行用#开头的注释来表示，但用3个单引号（' ' '）或者3个双引号(" " ")将注释进行标识会更自然。

　　在Python中，三引号（'''……'''）或者（"""……"""）是字符串定界符。所以，如果三引号作为语句的一部分出现，那么就不是注释，而是字符串，要注意区分。

例如，以下代码即为多行注释：
 

'''
这是一个多行注释：
山河远阔，人间烟火，无一是你，无一不是你。
词语欣赏：
在千山万水的风景里，在日出日落的生活里，你都不在身边，但是每一处风景中都能看到你的影子，因为你在我心里。
'''
'
运行
运行

以下的代码为字符串：

print('''山河远阔，人间烟火，无一是你，无一不是你。''')
print("""山河远阔，人间烟火，无一是你，无一不是你。""")
'
运行
运行

输出结果：
山河远阔，人间烟火，无一是你，无一不是你。
山河远阔，人间烟火，无一是你，无一不是你。

3.1、多行注释第一种形式

    '''
        第一行注释内容
        第二行注释内容
        第三行注释内容
        ……
    '''

 '''
上堂开示颂
黄蘖禅师〔唐代〕
尘劳迥脱事非常，紧把绳头做一场。
不经一番寒彻骨，怎得梅花扑鼻香。
 '''

 

3.2、多行注释第二种形式

    """
        第一行注释内容
        第二行注释内容
        第三行注释内容
        ……
    """

"""
上堂开示颂
黄蘖禅师〔唐代〕
尘劳迥脱事非常，紧把绳头做一场。
不经一番寒彻骨，怎得梅花扑鼻香。
"""
'
运行
运行

四、中文注释

　　Python中，有一种特殊的中文注释。该注释的出现主要是为了解决Python 2.x中不支持直接写中文的问题。但是为了规范页面的编码，也为了方便其他人及时了解文件所用的编码，通常都建议在文件开始加上中文注释。

中文注释语法格式如下：

# -*- coding:编码 -*-

或者

    #coding=编码

在上面的语法中，编码为文件所使用的字符编码类型，

如果采用UTF-8编码，则设置为utf-8；

如果采用GBK，则设置为gbk或cp936。

例如，指定编码为UTF-8，可以使用下面的中文注释。

# -*- coding:utf-8 -*-
'
运行
运行

或

# coding:utf-8
'
运行
运行

或

#coding=utf-8
'
运行
运行

编码出错乱码，中文显示乱码问题：

　　如果代码中有汉字中文，运行的时候python报错，出现python中无法正常输入中文，乱码等情况：

编译提示：SyntaxError: (unicode error) 'utf-8' codec can't decode byte 0x*** in position 0: ...

出错原因：主要是由于编码的问题引起的。

解决办法：

　　受开发系统和环境不同影响，解决办法会有所不同，但一般按以下办法处理就能解决，有需要者请自行尝试适合自己系统的解决办法：（记住，下面的方法不需要全部添加到python文件中，选择其中一项或两项尝试，能解决问题即可）

在你的python文件（.py）文件第一行

1、开头加入

# coding=utf-8
'
运行
运行

　　# coding=utf-8

2、或者开头加入

#-*- coding: UTF-8 -*-
'
运行
运行

　　#-*- coding: UTF-8 -*-

3、或者开头加入

　　#!usr/bin/env python3
 
　　# -*- coding:utf-8 -*-

　　#!usr/bin/env python3

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

4、或者开头加上

# -*-coding:GBK -*-
'
运行
运行

　　# -*-coding:GBK -*-

5、或者开头加上

　　#coding=utf-8

　　import sys

　　reload(sys)

　　sys.setdefaultencoding("utf-8")

6、改变标准输出print()的默认编码

　　sys.stdout = io.TextIOWrapper(sys.stdout.buffer,encoding='gb18030')

平时开发python时注意：

　　1、如果你用pycharm编译书写python代码，pycharm默认是会自动保存为UTF-8格式的，如果你无意中修改过，请在pycharm工作界面右键—File-Encoding–选择UTF-8编码----reload-----reload anyway。如果还是不行，试一下路径改为全英文。

　　pycharm设置参考链接：https://blog.csdn.net/qq_35091353/article/details/108236018

　　2、如果你用其他编译书写代码工具，请点击

　　文档>>设置文件编码>>Unicode>>Unicode(UTF-8)

　　3、如果你用visual studio 编译书写python代码，

　　visual studio 2022下python编程，报错：SyntaxError: (unicode error) 'utf-8' codec can't decode byte 0xc8 in position 0: invalid continuation byte

　　解决办法：

把Visual studio的文件保存编码改为UTF-8：

---->Unicode(UTF-8带签名)-代码页65001

visual studio其他版本在文件菜单选项里选“高级保存选项”

---->Unicode(UTF-8带签名)-代码页65001

设置工程字符集为utf-8,选择工程----右键----属性----加上字符集编码

Visual Studio Community 2022 - UTF-8 编解码器问题 #6784,可参考阅读：

https://github.com/microsoft/PTVS/issues/6784

五、拓展说明

5.1、嵌套结构

　　在 Python 中，多行注释是由三个单引号 ''' 或三个双引号 """ 来定义的，这种注释方式并不能嵌套使用。

　　当开始一个多行注释块时，Python 会一直将后续的行都当作注释，直到遇到另一组三个单引号或三个双引号。

嵌套多行注释会导致语法错误。

例如，下面的示例是不合法的：
 
'''
这里是正常多行注释第一行注释内容
这里是正常多行注释第二行注释内容
    '''
    这里如果嵌套多行注释
    会导致语法错误
    '''
'''

这个例子中，内部的三个单引号并没有被正确识别为多行注释的结束，而是被解释为普通的字符串。

这将导致代码结构不正确，最终导致语法错误。

如果你需要在注释中包含嵌套结构，

推荐使用单行注释（以#开头）而不是多行注释。

单行注释可以嵌套在多行注释中，而且不会引起语法错误。
例如：

'''
尘劳迥脱事非常，
紧把绳头做一场。
不经一番寒彻骨，
怎得梅花扑鼻香。
# 诗词名：上堂开示颂
# 作者：黄蘖禅师〔唐代〕
'''
 
这样的结构是合法的。

str="""逆境清醒:
最好的友谊，
是各自忙碌无法联系，
但又彼此惦念。
"""
print(str)
'
运行
运行

输出结果为：

逆境清醒:
最好的友谊，
是各自忙碌无法联系，
但又彼此惦念。

5.2、函数的注释

输出函数的注释实例

def Comments():
    '''逆境清醒'''
    pass
print(Comments.__doc__)
'
运行
运行

输出结果为：

逆境清醒

当函数中有语句的时候，是无法输出函数的注释的:

def Comments():
    date=20240821
    '''逆境清醒'''
    pass
print(Comments.__doc__)
'
运行
运行

输出结果为：None

如果要输出函数中的注释，注释应该放在函数的第一行：

def Comments():
    '''逆境清醒'''
    date=20240821
    pass
print(Comments.__doc__)
'
运行
运行

输出结果为：逆境清醒

五、放松一下，一起来欣赏一下大能们有趣的注释（转自网络）

1. 只有上帝知道

//我写这一行的时候，只有上帝和我知道我在写什么

//现在，只有上帝知道了

2. 相隔时空的diss

//somedev1 -  6/7/02 添加对登录屏幕的暂时追踪功能

//somedev2 -  5/22/07 暂时个屁

（仿佛看到两个程序员相隔时空的diss）

3. 喝大了

//喝大了，等会再修bug

4. 有魔法，别碰

//有魔法，别碰。

5. 开森吗？

//开森地调bug吧，傻x

（隔着屏幕都想打他一顿）

6. 糊弄过去算了

/*

*你可能觉得自己看懂下面的代码了，

*然而你并没有，相信我。

*糊弄过去算了，不然你会好多个晚上睡不着觉，

*嘴里骂着这段注释，觉得自己很聪明，

*真能“优化”下面的代码。

*现在关上文件，去玩点别的吧。

*/

7. 你懂的

//这代码真是烂透了，你懂的，我也懂的。

8. 先往下看

//先往下看，后面再喊我傻X。

9. 好怕怕

//我也不确定我们到底需不需要这个，但是删了又特害怕。

10. 到底要怎样？

#要想理解递归，移步本文件底部

然后翻到文件底部：

#要想理解递归，移步本文件顶部

11. 本人对本代码概不负责

//本人对本代码概不负责，

//他们让我写的，非本人自愿。

12. 我偏不

//就不给你们写注释

//这代码写得这么费劲

//所以你们读着也得费劲

13. 没有错，不好用就不是我写的

//如果这段代码跑的通，那就是Paul DiLascia写的。要是跑不通，

//那我就不知道是谁写的了

14. 没毛病

//这公式没毛病，你要不信自己去算

15. 就问你服不服

//要是你想被炒鱿鱼，那就删吧

16. 好好活着

//如果将来读到这行代码，我会穿越回来，然后一死以谢天下。

17. 谨以此代码献给我的老婆

//谨以此代码和我所有的工作献给我的老婆Darlene，

//这段代码要是放出去，

//她就得照顾我还有三个孩子了。

（潜台词是自己代码写的太烂，会丢了工作或者造成公司倒闭）

18. 我读书少，别骗我

//别删这行注释啊，删了程序就崩了

19. 仇恨绵绵不绝

放个大招，在 GitHub 上有这么一个脚本，前面好好的，很正常，到了中间作者忽然用注释对 Adobe PSD 来了一大段的疯狂吐槽：

//到了这个份儿上，我得给你说说这个 Adobe PSD 格式。

//PSD 可不是个好格式，它甚至都是不个坏格式，叫它坏格式都是

//对 PCX 和 JPEG 这些坏格式的一种侮辱。不，PSD 是一种烂到家的格式。

//我忙活这段代码好几个星期了，我对 PSD 日渐增长的仇恨，

//如同数百万个太阳燃烧成的怒火，绵绵不绝。

//如果有两种不同的做事方法，PSD 会两个都试一遍。

//然后再以正常人无法想象的方式想出三个甚至三个以上的方法，

//把它们也都试一遍。PSD 把“前后矛盾”上升成了一门艺术。比方说，

//为啥它忽然就决定这些特定组块对齐 4 比特，而且这种对齐方式

//不应该包含在尺寸内？其它地方的组块要么没对齐，

//要么对齐方式包含在尺寸内。这里就没包含在内。

//这三种方式任何一种都是可以的，智商正常的格式都会只用一种，

//我们的 PSD 当然是三种都用了，而且不止三种。

//从 PSD 文件里拿到数据，就跟从你那 58 岁生日时被一条抓狂的淡水鲨鱼干掉的

//上岁数的怪叔叔家的阁楼上想找出点好东西一样。

//用鲨鱼这个比方不是我要表达的重点啊，但是我现在正在苦思冥想，

//那些小题大做搞出这种文件格式的人该有怎样搞笑的人生啊。

//之前吧，我想找到这种文件格式的最新说明书。

//为此，我必须向他们申请许可，他们才考虑送我

//这本神圣的“秘籍”。整个过程还得向他们传真

//一些文件的复印件，或者可能还得签点秘密协议。

//我只能觉得，他们把这个流程搞这么复杂就是因为

//他们造出了这么恶心的东西，心里有愧。我是自然不会

//按他们的意思走这个流程的。但是假如我真的

//这么做的话，我会把说明书的每一页都打印出来，

//一把火给它烧了。要是能有超能力，

//我会把说明书的所有复印件都收集过来，

//放到宇宙飞船上，直接发配到太阳。

//

//PSD 不是我喜欢的文件格式。

看来是实在忍无可忍了。吐槽完这一段后，作者又继续淡定地写完了脚本。

这段脚本的地址：

https://github.com/zepouet/Xee-xCode-4.5/blob/master/XeePhotoshopLoader.m#L108

20. 新人默默的在后面增加一行注释：浪费在这里的总时间=48h

21. 新人看到这样的注释都不用再尝试了，感恩前辈

22. 即使系统终止运行，这个BUG依然存在

23. 只能说下家公司真惨，这是有多大的积怨呢

24. 整个网站就此垮掉......

25. 敢这么诅咒老板的，我敬你是条汉子

26. 你不可能看懂这个

这是一段来自贝尔实验室的，第六版Unix Kernel，注释语句为“you are not expected to understand this”，意思就是，你不可能看懂这个。

27. 穷逼VIP

去年虾米音乐客户端的程序员竟然称一些活动送的VIP客户为“穷逼VIP“，引发了网友争议。

28. 不解释，看注释

29. 听前辈的话，把这块程序去掉就好了

30. 调试了半天才看到这个，新人表示已泪奔

31. 你有freestyle吗，也来一个？

32. 顾客要是不会看个代码注释，被坑了可能还不知道

33. 虽然没有年终奖，但我们有很多bug呀！

刚入职的程序员估计会被吓跑，然后感谢一下前辈。

34. 就连Nike也尝试了在他们的robots文件里加入了一个有趣的图案

35. 超级有自知之明的代码注释

36. 致敬每一个勇敢的编程骑士

37. 当然，闲的蛋疼的猿，还会做这样的注释

或者这样的：

甚至这样的：

38. 据说下图是程序员写注释时的基本思路

39. 最后，送给广大开发者们，恭祝代码无Bug

 

   推荐阅读：

Python教程__目录

Python注释（详解）

自言自语的独角戏小丑“讲”的“演讲”，看吗？http://iyenn.com/rec/1695179.html