Is it Pythonic to have "header" comments in a Python script

Question

I have a question for the Python community about block comments within a Python script. I've read through PEP-8, and while a lot of the ideas and standards make sense for developing a clean module or package, I didn't see much about short Python scripts.

What I mean is, suppose I decide to make a very quick Python executable script that serves as a command line utility for running the business logic in my module.

In this command line utility, a large portion is just the setup of an argparse parser with long docstrings, followed by an entry point into the script, with a few helper functions along the way.

My style for creating this has been something like this:

############################################################
# 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)

...

Even though this isn't covered by PEP-8, I've found that this tends to be pretty readable (assuming my variable names are much better) and the block comments really help in figuring out quickly where everything is. Also, since this ends up being an executable script packaged with my application, it makes sense to keep it in one file since all it really is, is a glorified argument parser.

Is there a more Pythonic approach to this?

Answer 1

I think the consensus is: no.

It's much better to split up your module into a package:

- package_name
 ∟ __init__.py
 ∟ __main__.py
 ∟ args.py
 ∟ helpers.py

Note: You might want to give "helpers" a more descriptive name (like you said).

Some reasons this is preferred:

• Header comments can go stale (insert function in wrong section).
• Function/class names are much better to describe what the thing does e.g. if it's called parser and uses argparse it's clearly to do with argument parsing; what does the header comment add?? (I'm necessarily already reading the source code: this header comment has no value.)
• When adding new functionality, you must consider which file it should go into, rather than dump it wherever...
• Separate business logic from the argument parsing, being in separate files encourages that. Also separate distinct families of functions.
• Similarly testing is easier, separate concern and enumerated abstractions you should test.
• You can document each file, that way anyone using your package can see how it is structured/how it works... without having to read the whole thing.
• Projects invariably get bigger and will be a mess if kept in a single file.
• Debugging can be slightly easier (perhaps I'm reaching now).
• Python has solved this problem with packages (and __main__.py), don't reinvent the wheel.

---

That said:

it makes sense to keep it in one file since all it really is, is a glorified argument parser.

There's always going to be an argument for writing a script quickly and putting it out the door.

If you want something that's more maintainable in the long-term, readable, and ...pythonic. Consider putting it in a directory/package.

Shipping a single file, might be better with a proper build tool like pex. See this talk.