2.2.5 正确的注释
注释是用于说明代码实现的功能、采用的算法、代码的编写者以及代码创建和修改的时间等信息。注释是代码的一部分，注释起到了对代码补充说明的作用。C、C++、Java均采用“//”或“/**/”作为注释的标记，Python的注释方式有所不同。如果只对单行代码注释，使用“#”开始，后面是注释的内容。如果对多行代码进行注释，使用三个单引号'''或者三个双引号"""将注释括起来。Python解释器会自动忽略注释的内容，不会被当作代码进行处理。下面的代码演示了Python的注释。
1．单行注释
01 # 规范的变量命名 02 sumPay = 0 # 年薪 03 bonusOfYear = 2000 # 年终奖金 04 monthPay = 1200 # 月薪 05 sumPay = bonusOfYear + 12 * monthPay # 年薪 = 年终奖金 + 12 * 月
【代码说明】
·第1行把注释放在代码的最前面。
·第2～5行把注释放在每行代码的后面。
2．多行注释
01 """ 02 以下程序的功能是声明和调用函数getv(b,r,n) 03 根据本金b,年利率r和年数n，计算最终收益，计算最终收益的公式为v=b(1+r)n 04 """ 05 def getv(b,r,n): # 定义一个getv函数 06 v=b*((1+r)**n) 07 return v # 返回v的值 08 sv=getv(15000,0.8,10) # 调用函数 09 print(sv) # 输出sv的值
【代码说明】
·第1行以三个双引号开始，也可以以三个单引号开始。
·第2～3行为注释内容。
·第4行三个双引号结束，也可以以三个单引号结束。
·第5行到第9行的代码实现程序的功能。
3．特殊的注释
Python还有一些特殊的注释，完成一些特别的功能，如中文注释、程序的跨平台。
1）中文注释：如果需要在代码中使用中文注释，必须在Python文件的最前面加上如下注释说明。
# -*- coding: UTF-8 -*-
注意 Python3中默认的编码是Unicode，所以不需在每个Python文件中再加以上注释，但在Python2中若使用中文则必须加上。
2）跨平台注释：如果需要使Python程序运行在Linux或UNIX系统中，最好在Python文件的最前面加上如下注释说明。
#!/usr/bin/python
此外，注释也用于调试程序。由于文本编辑器不具备调试功能，因此，可以使用注释辅助调试。如果一个程序很长，可以把程序分成若干个部分编写。为了更好地调试目前正在编写的程序模块，可以将那些已经编译通过的部分注释掉；或者把多余代码注释掉，把主要精力集中在当前编写的逻辑上。
例如，【例2-4】编写一个比较两个数字大小的函数。
【例2-4.py】
01 def compareNum(num1, num2): # 定义compareNum函数 02 if(num1 > num2): # if判断，比较两个数的大小，返回不同的结果 03 return str(num1)+" > "+str(num2) 04 elif(num1 < num2): 05 return str(num1)+" = "+str(num2) 06 elif(num1 == num2): 07 return str(num1)+" = "+str(num2) 08 else: 09 return ""
【代码说明】
·第1行定义函数compareNum，带两个参数num1和num2。
·第2行到第9行if条件判断，如果num1>num2就返回"num1">"num2"，如果num1<num2就返回"num1"<"num2"，如果num1==num2就返回"num1"="num2"，否则就返回空字符串。
·本段代码中的str()函数实现了数字类型到字符串类型的转换。
编译后显示如下内容：
---------- python ---------- 输出完成 (耗时: 1 秒) - 正常终止
说明这个函数编译通过，至少在语法上没有任何错误。下面就可以编写这个函数的调用程序，证明这个程序的逻辑是否正确。在前面的代码段后面添加如下代码。
01 num1 = 2 02 num2 = 1 03 print (compareNum(num1, num2)) 04 num1 = 2 05 num2 = 2 06 print (compareNum(num1, num2)) 07 num1 = 1 08 num2 = 2 09 print (compareNum(num1, num2))
运行程序，发现第3行的输出结果有误。
2 > 1 2 = 2 1 = 2
第1行和第2行的输出证明函数compareNum()中num1>num2和num1==num2的判断是正确的，于是想到程序可能是在num1<num2的条件判断的逻辑上出现了错误。为了证明这个观点，注释掉num1<num2的分支判断语句。注释后的compareNum()的代码如下。
01 def compareNum(num1, num2): 02 if(num1 > num2): 03 return str(num1)+" > "+str(num2) 04 #elif(num1 < num2): 05 # return str(num1)+" = "+str(num2) 06 elif(num1 == num2): 07 return str(num1)+" = "+str(num2) 08 else: 09 return ""
此时，程序编译通过，证明逻辑错误就在num1<num2的分支语句中。仔细检查注释的语句，发现return语句的返回值表达式写错了，其中的“>”误写为“=”。compareNum()正确的写法如下所示。
01 def compareNum(num1, num2): 02 if(num1 > num2): 03 return str(num1)+" > "+str(num2) 04 elif(num1 < num2): 05 return str(num1)+" < "+str(num2) 06 elif(num1 == num2): 07 return str(num1)+" = "+str(num2) 08 else: 09 return ""
再次运行整个程序，输出结果正确显示。
2 > 1 2 = 2 1 < 2
合理地使用注释可以检查程序中的错误。这段代码演示了注释问题语句的做法，并检查这些语句错误的过程。另一种用法是，注释正确语句，单独运行问题语句，检查语句错误。这两种用法可以根据实际情况分别应用，后者更适合于代码比较长的情况。注释对于程序非常重要，表2-1说明了注释的用法和作用。
表2-1 注释的用法
