注释可以给代码增加可读性,在 Python 中支持单行注释和多行注释。本节教程中将讲解 Python 如何添加注释和使用的样式。
编写注释是好的编程习惯。它在代码中不会被执行,但是却很重要。因为这能对读代码的人帮助很大,比如程序测试人员可以参考注释让白盒测试变得更加容易。
添加注释最好的方法是在程序创建和更新的开头,因为这有助于关联程序的上下文关系。
添加注释
注释是一种优先级非常高的表达式,带标记的文本行,用来注释一段代码。在 Python 中有两种注释风格,分别是单行注释和多行注释。
单行注释
在调试代码添加注释时,大多数会选择单行注释。单行注释以井号(#)开头,并自动以行末结尾。
# Good code is self-documenting.
print("Learn Python")
在写注释时,要确保注释和下方的代码有同样的缩进,特别是在内部注释代码块时要注意对齐。
# Define a list of months
months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
# Function to print the calender months
def showCalender(months):
# For Loop that traverses the list and prints the name of each month
for month in months:
print(month)
showCalender(months)
多行注释
Python 允许跨行注释,这种注释称为多行注释或块注释,可以用来描述更复杂的内容。
使用井号(#)标记
多行注释应该每行井号(#)开头,后跟一个空格,这样注释就可以分为几段。
# To Learn any language you must follow the below rules.
# 1. Know the basic syntax, data types, control structures and conditional statements.
# 2. Learn error handling and file I/O.
# 3. Read about advanced data structures.
# 4. Write functions and follow OOPs concepts.
def main():
print("Let's start to learn Python.")
...
文档字符串
Python 具有文档字符串(docstring)功能。它为每个 Python 模块、函数、类和方法快速添加注释。只要在每个对象(模块、函数、类和方法)的第一个语句中定义字符串常量即可。
文档字符串的范围比 Python 注释要广很多。所以,它应该拿来描述函数是做什么、不做什么,等等。对于任何程序来说,添加文档字符串是一个好习惯。
定义文档字符串
可以用三个引号(''')来定义文档字符串。在注释的开头和结尾各添加一个。就像多行注释一样,文档字符串也可以叠加成多行。
注释和文档字符串有什么不同?
因为三引号开头的字符串是常规字符串,所以是可被执行的语句。如果没有特殊标记文档字符串,那么在代码块执行完成后将会进入垃圾回收。
Python 的解释器不会像注释一样忽略文档字符串。所以,如果将这样的字符串放在函数和类定义之后或模块顶部,那么就会被 Python 解释器认为这段字符串是文档字符串。
可以使用 __doc__
变量调用文档字符串:
myobj.__doc__
例子:
def theFunction():
'''
This function domaonstrate the use of docstring in Python.
'''
print("Python docstring are not comments.")
print("\nJust printing the docstring value...")
print(theFunction.__doc__)
小结
在程序中添加注释和文档字符串会让代码具有更好的可读性和维护性。即使以后需要重构代码,因为有注释也会让这个过程变得容易理解很多。
就像这句话说的一样:
Software spends only 10% time of its life in development and rest of 90% in maintenance.
所以,在项目代码中尽量添加注释和文档字符串往往有助于将来的维护工作。