Question

首先，我不知道是否有一些好的规则或通用做法来添加使用Python脚本的注释。这是我的问题。

在python脚本中，包含函数的定义，以及下面的部分 if __name__ == '__main__':，我应该在哪里添加评论使用if __name__ == '__main__':下方的部分：在...之上 shebang下面的脚本，或if __name__ == '__main__':以下的脚本？

例如，

#!/usr/bin/env python                             


import argparse


def myfun():
    ...

if __name__ == '__main__':

    parser = argparse.ArgumentParser(description='A script of writing comment of usage')
    parser.add_argument('--in', dest='in', help='an input file')
    parser.add_argument('--out', dest='out', help='an output file')
    args = parser.parse_args()

我对使用if __name__ == '__main__':下方部分的评论是调用脚本的示例：

''' Example:                                                                                                                                                   
myscript.py --in infile --out outfile
'''

我应该在脚本中添加它？

在评论脚本的使用时，除了举例外，我还要加什么？我认为选项是自我清晰的 parser.add_argument()，脚本的目的是自我清晰在argparse.ArgumentParser()？

例如，从上面的示例中，以下内容足够了解释脚本的目的和选项？
```
    parser = argparse.ArgumentParser(description='A script of writing comment of usage')

    parser.add_argument('--in', dest='in', help='an input file')
    parser.add_argument('--out', dest='out', help='an output file')
```

感谢。

Answer 1

标准Python模块/脚本文档按如下方式完成。

#! /usr/bin/env python 

"""
Leave your docs here. Describe the behaviour of your main function. E.g. 
The script does blah-blah... 
Standard usage: myscript.py --in infile --out outfile
"""

import ...

除此之外，您还可以修改help中的argparse参数以显示标准用法。顺便说一下，if __name__ == "__main__"行与主函数（它通常称为main）结合使用。关键是要将所有处理保留在main函数中，例如

#! /usr/bin/env python  

"""
The script does blah-blah...
Standard usage: ...
"""

def foo(args...):
    ...

def ham(args...):
    ...

def main():
   # do something with foo and ham 

if __name__ == "__main__":
   main()

Answer 2

如果您使用argparse（而不仅仅是添加评论），我建议您在文件顶部创建一个main函数。把评论放在那里。然后，在main()块内调用if __name__ == "__main__。

这就是帮助，放置评论的常见位置是顶部的三引号字符串，因为这是人们在阅读代码时首先看到的内容。

底线是你想让你的代码易于理解。强迫用户去寻找评论并不容易。

添加使用python脚本的注释？

2 个答案: