为使用python脚本添加注释？

Question

首先，我不知道在添加注释以使用Python脚本时是否存在一些好的规则或惯例。这是我的问题。

1. 在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
   '''
   

   我应该在脚本的哪个位置添加它？

2. 在提供脚本用法的注释中，除了提供示例之外，我还应该添加什么？我认为选项在中是很明确的 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()