Coding

Standalone scripting guidelines

schimpy has a number of standalone command line scripts. In order to make sure that our command line scripts work well please follow these guidelines:

1. The script should have a if __name__ == __main__ block that does nothing but call a function called main().
2. The main() function should be called main().
3. The main role of main is to act as glue between argument parsing and files that do more of the real work. The function should call create_argparse(), gather concrete arguments and call a function with named arguments. Please stick with argparse for schimpy or vtools. If we switch we should switch as a team. The bigger problem in our group isn't the use of a suboptimal command line library, but rather ignoring all the rules and having a bunch of linear scripts that are not amenable to automatic documentation. Argparse does fine with this, but it is much easier to use the automata if you name your function create_argparse.
4. There should be a "real work function" in your script that takes data structures or at worst file names and does processing. You should design your real work function to be callable programmatically from other contexts. You may learn more about this later.
5. The real work function should take named arguments means named arguments, not dictionaries, namespaces and argparse objects. Those are a lot like the old common blocks in fortran ... it is fairly hard to create a testable programming contract. One exception is if you are passing through arguments to libraries that expect this (matplotlib for instance). Heavy use of optional arguments is hard to support and seldom justified -- it thwarts automatic documentation.
6. If there is only one main concrete work funciton, consider naming it the same thing as the file to reflect the centrality of purpose.
7. The concrete function should be documented using numpydoc conventions.
8. The function create_argparse should be named create_argparse. We use this to hook up to sphinx.
9. Once stable, recommend you add standalones as entry points in setup.py.
10. Use Python PEP8 for naming things. Please. No_More_This or functionBasedOnJavaNaming.

For newer libraries feel free to use fancier CLI methods.