如何用评论来描述Python脚本

Question

我有一个可以完全独立运行的python脚本。我以某种方式想创建脚本在评论中所做的事情的一般描述。

这样做的Pythonic方法是什么？就像我下面的示例一样吗？不知何故，在进口之前有它是错误的，但我不确定吗？

作为一个例子：

"""
This is the example description
"""
import argparse
from datetime import datetime
import re
import sys
from xml.etree import ElementTree

def some functions():
    x = x+1

Answer 1

"""
Here you can add the copyright contents
This is the overall description of this script 
And the available classes/functions in this script
You can also add usage
"""
import argparse
from datetime import datetime
import re
import sys
from xml.etree import ElementTree

def some functions():
    """
    This is function related description what is this function and how it works
    You can also add expected input and output information
    """
    x = x+1 #adding 1 in the input
    # comment for the below complicated logic
    # Explain the below logic
    x = x*x*1*2*x 

您可以看到此页面以获取更多评论实践。

Answer 2

这是PEP 257 -DocString惯例必须对此说：

脚本的docstring（独立程序）应可用为 它的"用法"消息，当脚本不正确时打印 或缺少参数（或使用" -h"选项，以"帮助"）。这样的 DocString应记录脚本的功能和命令行 语法，环境变量和文件。使用消息可以公平 精心制作（几个屏幕已满），应该足以进行新的 用户可以正确使用命令，以及完整的快速 参考复杂用户的所有选项和参数。

Answer 3

第一件事：请注意，三重引用的字符串不是"注释"，它们是真正的python字符串。碰巧它们也通常用于 docStrings （DocString只是一个字符串，只是在模块，类或功能的开头，Python用作此模块/类的" help help"字符串/函数），因为您通常在这里需要多个行，但只有任何字符串都可以。

评论当然是以#开头的行，而Python完全忽略了。

现在您说：

我想以评论中的脚本做出的一般描述。

如果您想要的是真正的评论，请使用评论语法。如果您想要的是Python可以用于文档的东西（例如IE import yourmodule; help(yourmodule);，然后使用DocString。

Answer 4

使用此模板：

"""
Author: YOU
"""
import argparse
from datetime import datetime
import re
import sys
from xml.etree import ElementTree

def some functions():
    """
    This is a description .....
    """
    x = x+1 #adding 1 in the input (this is a comment)

Answer 5

使用主题标签（#）。以主题标签开头的行不被读为代码。