Добавить комментарий для использования скрипта python?

Question

Во-первых, я не знаю, есть ли какое-то хорошее правило или обычная практика для добавления комментариев для использования скрипта Python. Вот мой вопрос.

1. В питон скрипт, с определением функций, а часть ниже if __name__ == '__main__':, где я должен добавить комментарий для использования части ниже if __name__ == '__main__':: в верхней части сценария ниже притон, или ниже 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, чтобы показать использование стандартного. BTW, линия 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__.

Эта помощь, общее место для размещения комментариев находится в тройной кассете на самом верху, так как это первое, что люди видят при чтении кода.

Суть в том, что вы хотите сделать свой код понятным. Принуждение пользователя к поиску комментариев не облегчает.