注释 —— Python教程

注释能够给代码增长可读性，在 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.

因此，在项目代码中尽可能添加注释和文档字符串每每有助于未来的维护工做。