Standardize Code

[ajmedford]

Adding doc strings to functions, make all lines shorter than 80 characters, hunt down CamelCase variable names, clean up any other instances of laziness on AJ's part.

[mhoffman]

No automatic documentation tool, yet :-/. However in order to make all lines < 80 characters etc. there is a great tool called autopep8 (also in macports), which has the 'autopep8 --in-line ', which is as painless as can be.

[ghost]

I could try to add documentation as I go through and learn how CatMAP is written. Of course, someone will have to double check to make sure I haven't misunderstood anything.

[mhoffman]

That sounds great! I have already set my mind on doing something very similar. If you look at the modest documentation I have added so far, you'll see that I stick to the python-sphinx notation[1] for the function level documentation via docstrings, e.g. here[2]. I would also like to keep documenting as I dig more and more into the code base. So my question is if it is ok for the AJ if we stick to the sphinx style? It usually makes for very readable API docs.

I will try to keep pushing docstrings as soon as possible to avoid redundant work to my 'develop' branch. @ctsai89 could you post the branch, where you intend to push your documentation? That way I can check before writing new docstrings on my side?

[1] https://pythonhosted.org/an_example_pypi_project/sphinx.html#function-definitions [2] https://github.com/ajmedford/catmap/blob/master/catmap/model.py#L644

[ajmedford]

This sounds like a great idea, and a good way to learn the code. I agree that python-sphinx is the best choice, so lets go with that. Perhaps we can also use some flags for places where you are particularly unsure or confused, then I can go back to those and try to decipher my own code and elaborate.

[mhoffman]

At this point it may be also worth pointing out that there is a widely accepted standard for code layout called PEP8 as well as a tool called autopep8 that automatically converts code to conform with said PEP. When doing the documentation make-over could also apply this tool? It will probably work everywhere out of the box except for catmap/data/templates.py

[chuanshi]

sounds good to me. Let's do it

On Wed, Apr 22, 2015 at 7:09 PM, Max Hoffmann [email protected] wrote:

At this point it may be also worth pointing out that there is a widely accepted standard for code layout called PEP8 https://www.python.org/dev/peps/pep-0008/ as well as a tool called autopep8 https://pypi.python.org/pypi/autopep8/1.1.1 that automatically converts code to conform with said PEP. When doing the documentation make-over could also apply this tool? It will probably work everywhere out of the box except for catmap/data/templates.py

— Reply to this email directly or view it on GitHub https://github.com/ajmedford/catmap/issues/1#issuecomment-95391914.

[charlietsai]

I just noticed this again and made a small script for running autopep8 on all python files.