分类
文章

了解Python注释,多行注释和DocString

注释就像路标一样,使给定的代码不言而喻且可读性强。在Python中,我们可以添加单行和多行Python注释。本教程将详细介绍这两种方法。阅读本文之后,您将知道如何添加Python注释以及使用哪种样式。

编写注释是一种好的编程习惯。它们是代码的不可执行部分,但在程序中却非常重要。这些不仅可以帮助从事同一项目的其他程序员,而且测试人员还可以参考它们,以使白盒测试更加清晰。

最好在创建或更新程序时添加注释,否则可能会丢失上下文。而且以后写的评论可能没有达到应有的效果。

+阅读: Python中的语句,表达式和缩进

如何在Python中使用注释?

注释是一种非常高级地表达程序将要执行的操作的艺术。这些是带标记的文本行,用于注释一段代码。在Python中,我们可以应用两种注释风格:单行和多行。

单行Python注释

当需要简短,快速的注释进行调试时,您可能更喜欢使用单行Python注释。单行注释以井号(#)开头,并自动以EOL(行尾)结尾。


# Good code is self-documenting.

print("Learn Python Step by Step!")

在发表评论时,请确保您的评论与其下方的代码处于相同的缩进级别。例如,您可以注释没有缩进的函数定义。但是该函数可以在多个级别缩进代码块。因此,在内部代码块中进行注释时,请注意对齐。


# 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评论

Python允许注释跨越多行。这样的注释称为多行注释或块注释。您可以使用这种注释方式来描述更复杂的内容。

这种扩展的注释形式适用于以下部分或全部代码。这是使用多行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中的文档字符串

Python具有文档字符串(或文档字符串)功能。它为程序员提供了一种在每个Python模块,函数,类和方法中添加快速注释的简便方法。

您可以通过将文档字符串添加为字符串常量来定义它。它必须是对象(模块,函数,类和方法)定义中的第一条语句。

该文档字符串的范围比Python注释的范围大得多。因此,它应该描述函数的功能,而不是方法的功能。同样,对于程序的所有功能来说,具有文档字符串也是一种好习惯。

如何在Python中定义docstring?

您可以在三引号的帮助下定义文档字符串。在字符串的开头和结尾处添加一个。就像多行注释一样,文档字符串也可以重叠到多行。

注意:在Python中,使用三引号定义的字符串是docstring。但是,它可能会显示为常规注释。

注释和文档字符串之间有什么区别?

以三引号开头的字符串仍然是常规字符串,除了它们可能会传播到多行之外。这意味着它们是可执行语句。如果未标记它们,则在代码执行后将立即对其进行垃圾回收。

Python解释器不会像注释一样忽略它们。但是,如果将这样的字符串放在函数或类定义之后或模块顶部,则它们将变成文档字符串。您可以使用以下特殊变量访问它们。


myobj.__doc__


def theFunction():
    '''
This function demonstrate the use of docstring in Python.
    '''
    print("Python docstrings are not comments.")

print("nJust printing the docstring value...")
print(theFunction.__doc__)

总结– Python注释和文档字符串

注释和文档字符串将值添加到程序中。它们使您的程序更具可读性和可维护性。即使您以后需要重构相同的代码,使用注释也将更容易。

软件仅将生命周期的10%花费在开发上,将其余90%的时间花费在维护上。

因此,请始终放置相关且有用的注释或文档字符串,因为它们会导致更多的协作并加速代码重构活动。

发表评论

电子邮件地址不会被公开。 必填项已用*标注