在 Python 脚本中有“标题”注释是 Pythonic 吗？

Question

我对 Python 社区有一个关于 Python 脚本中块注释的问题。我通读了 PEP-8，虽然很多想法和标准对于开发一个干净的模块或包都很有意义，但我对简短的 Python 脚本并没有看到太多。

我的意思是，假设我决定制作一个非常快速的 Python 可执行脚本，用作在我的模块中运行业务逻辑的命令行实用程序。

在这个命令行实用程序中，很大一部分只是设置一个带有长文档字符串的 argparse 解析器，然后是脚本的入口点，以及一些辅助函数。

我创建它的风格是这样的：

############################################################
# Helper functions
############################################################

def helper1(arg):
    pass # things happen

def helper2():
    pass

...

############################################################
# Setup Argparse
############################################################

parser = argparse.ArgumentParser(description='Some description')

somedoc = """
Some long description for my first argument...
""".strip()

parser.add_argument('integers', 
    metavar='N', 
    type=int, 
    nargs='+',
    help=somedoc)

parser.add_argument('otherargs', 
    metavar='N', 
    type=int, 
    nargs='+',
    help='Some docstring')

...

############################################################
# Entry point
############################################################

if __name__ == '__main__':
    args = parser.parse_args()

    if len(args.integers) > 1:
        helper1(args.integers)

...

尽管 PEP-8 没有涵盖这一点，但我发现这往往是非常易读的（假设我的变量名要好得多）并且块注释确实有助于快速确定所有内容的位置。此外，由于这最终是一个与我的应用程序打包在一起的可执行脚本，因此将它保存在一个文件中是有意义的，因为它实际上是一个美化的参数解析器。

有没有更 Pythonic 的方法来解决这个问题？

Answer 1

我想大家的共识是：不会。

\n\n

最好将模块分成一个包：

\n\n

- package_name\n \xe2\x88\x9f __init__.py\n \xe2\x88\x9f __main__.py\n \xe2\x88\x9f args.py\n \xe2\x88\x9f helpers.py\n

\n\n

注意：您可能想给“助手”一个更具描述性的名称（就像您所说的）。

\n\n

这是首选的一些原因：

\n\n

\n
• 标题注释可能会过时（在错误的部分插入函数）。
\n
• 函数/类名称可以更好地描述该事物的作用，例如，如果它被调用parser并使用argparse它，那么它显然与参数解析有关；标题评论添加了什么？（我一定已经阅读了源代码：这个标题注释没有价值。）
\n
• 添加新功能时，您必须考虑它应该进入哪个文件，而不是将其转储到任何地方......
\n
• 将业务逻辑与参数解析分开，放在单独的文件中鼓励这样做。还可以分离不同的函数族。
\n
• 同样，测试更容易，您应该测试单独的关注点和枚举抽象。
\n
• 您可以记录每个文件，这样使用您的包的任何人都可以看到它的结构/工作原理......而无需阅读整个文件。
\n
• 项目总是会变得更大，如果保存在单个文件中，就会变得一团糟。
\n
• 调试可能会稍微容易一些（也许我现在已经达到了）。
\n
• Python已经通过包（和__main__.py）解决了这个问题，不要重新发明轮子。
\n

\n\n\n\n

那是说：

\n\n

\n

将它保存在一个文件中是有意义的，因为它实际上是一个美化的参数解析器。

\n

\n\n

对于快速编写剧本并将其推出的争论总是存在的。

\n\n

如果你想要一些长期可维护、可读且......Pythonic 的东西。考虑将其放入目录/包中。

\n\n

使用pex等适当的构建工具传输单个文件可能会更好。见此讲。

\n