新手必看：注释写法避坑指南

这篇解决什么问题

许多的新手们觉得那个注释的东西其实是不太重要的, 所以他们就会随便地写一下, 然后导致的结果就是:

今天是专门来讲注释。

把东西弄得简单一些、规范一些, 而且还要有实际用途, 只要你看完了之后, 就再也不会胡乱去写那些注释了。

一、什么是注释？

这注释就是专门给人看的那个东西, 它不是给程序去执行的什么有效指令的那类内容。

作用：

二、单行注释, 它的最常用表现形式就是用那个#号。

只要你在前面加上了一个井号, 也就是那个#符号, 那么整一行就不会被执行。

# 这是一行注释，程序不会管它

print("Hello Python") # 这是行尾注释

使用场景

a = 10

# a = 20 把这行注释掉，就不会执行

print(a) # 输出 10

三、所谓多行注释, 实际上就是通过连续使用三个引号来界定, 无论是采用双写的那种方式, 也就是三个双引号并排在一起, 还是采用三单引号连用的这种形式。

如果你碰到一段代码, 觉得它不需要被执行, 或者说想要在里面写下非常长的一大段说明文字的话, 那就去使用三引号。

"""

这是多行注释

可以写很多行

用来解释整个函数、整个类

"""

'''

也可以用单引号三引号

效果完全一样

'''

print("正常执行")

注意

其实多行注释这个东西, 在本质上它是一个字符串形式的内容存在的, 因为它并没有被赋值给任何具体的变量来使用, 所以从程序的运行机制来看它是不会触发报错行为的。

请尽量避免采用嵌套的方式来进行使用, 因为如果这样做了的话很有可能会让注释被提前结束从而引发报错情况的产生。

错误：

""" 外层注释

""" 内层注释 """ # 这里会提前结束，报错

"""

四、关于注释的这种规范性的书写方式, 它是那种专业级别的程序员们普遍都会按照这个标准来进行填写的写法。

1. 如果是在函数的上面或者类的上面的位置, 那么就应该去使用那种占有多行的注释内容, 用来把相关功能的情况给说明白。

def add(a, b):

"""计算两个数的和

参数：

a: 数字1

b: 数字2

返回：

和

"""

return a + b

2. 对于关键的逻辑部分旁边, 使用单行注释的方式进行简单的说明。

age = 18

if age >= 18: # 判断是否成年

print("已成年")

3. 不要过度注释

完全没有那个必要。

a = 10 # 把10赋值给a

这种纯属浪费时间的注释, 最终的结果就是会让原本就已经不太清晰的代码变得越来越混乱。

五、在注释里面存在着三个经常会遇到并且很常见的坑, 这些是那些刚入门需要赶紧避开的问题。

在坑一的环节里, 会出现中文的注释乱码这个问题。

具体的解决办法应当如下所示。

有一个坑叫作第二坑, 注释的缩进出现了不正确的情况, 这种情况导致了报错。

if True:

print(1)

# 注释不能乱缩进，否则影响代码结构

坑三这个情况是, 利用多行注释来暂时屏蔽一部分代码, 但是结果导致了嵌套方面出现错误。

"""

a = 1

""" b = 2 """ # 这里直接报错

六、在写代码的注释总结的时候, 可以记住三句口诀作为一行说明是用一个井号 # 符号开始的, 这种方式是简单方便的, 而对于大段的详细说明则需要使用三个双引号""" 这样的格式来包括起来, 只要能够把注释写得清晰而且不包含多余废话, 那么以后的代码就比较好维护了。

做注释, 这是程序员得具备的一个基本的素质。

你要是能够把你的注释给写得清清楚楚,那么你所写出来的代码在专业程度方面呢, 它就至少能够提升出一个档次来。