Python coding style and consistency

[mhidas]

Now that more of us are starting to write more Python code, it might be helpful to converge a bit in terms of coding style. In particular, naming conventions for variables, functions, classes and files. It just makes the code a bit more readable, so it's worth putting a bit of effort (not heaps) into it. As this detailed style guide for Python code suggests "A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is most important. "

My own code needs some cleaning up, but first we should agree on what to aim for. I propose we adopt the following conventions as an ideal:

• Use 4 spaces (not tabs) per indentation level, and >=4 spaces for long lines (examples)
• Module names (i.e. names of .py files) should be lower_case, with underscores if necessary
• Class names should use CapWords (capitalise first letter of every word, no underscores). If any word is an abbreviation, capitalise the whole word, e.g. use ANMNFileClassifier instead of AnmnFileClassifier
• Function names should be lower_case, with underscores between words (alternatively, if we decide we have too many in mixedCase already, we can stick with that, though IMHO they're less readable. Also we use the lower_case convention in our bash scripts)
• Variable names should be lower_case, same as functions
• Use leading underscores for non-public methods and variables
• Constants within a module should be defined at the top and use UPPER_CASE
• Docstrings - describe each module, class and function by adding a "triple-double-quoted" string directly after the definition, e.g.

    def do_something(arg):
        """Do something with arg and return the result.
        If no argument given, do nothing.
        """"

These are just suggestions, open for discussion.

[danfruehauf]

:+1:

What about unit tests? There are some kicking around, would be good to say something about that too.

My share of python is the ACORN Current Generator and I promise to align it to the code conventions specified here (mostly renaming function names).

[mhidas]

@lbesnard @bpasquer @ggalibert Any thoughts on this?

[bpasquer]

:+1:

[ggalibert]

Sounds good to me.

[lbesnard]

FIY : a bit faster with vim http://vim.wikia.com/wiki/Converting_variables_to_or_from_camel_case

[danfruehauf]

Module names (i.e. names of .py files) should be lower_case, with underscores if necessary Class names should use CapWords (capitalise first letter of every word, no underscores)

I think those 2 are contradicting somewhat. We're not using classes much, but image I have a modules called first_module.py and in it I have a class called SomeClass with a function called this_is_a_function. The result python code will look like:

import first_module # OK

first_module.SomeClass.this_is_a_function # AWKWARD

@mhidas I'd like to have your feedback on that...

[lbesnard]

a fair bit of work to do in data-services/lib/python/* if conventions need to be followed. until then it's not really possible to use these functions in different scripts at they are likely to be modified

[danfruehauf]

a fair bit of work to do in data-services/lib/python/* if conventions need to be followed. until then it's not really possible to use these functions in different scripts at they are likely to be modified

Bit by bit.

[mhidas]

@danfruehauf

first_module.SomeClass.this_is_a_function # AWKWARD

Personally I don't have a problem with this. For what it's worth, it does help distinguish a class from a module or sub-module. You can avoid having to write all that by importing it like this instead:

from first_module import SomeClass

Or would you prefer to use CapWords for module names as well?

[danfruehauf]

Or would you prefer to use CapWords for module names as well?

I just prefer to have consistency. I'm not bothered by any of that :)

[mhidas]

A minor point in the above mentioned style guide:

Note: When using abbreviations in CapWords, capitalize all the letters of the abbreviation.

So for example instead of AnmnFileClassifier I will have ANMNFileClassifier. Just a bit easier to read.

[danfruehauf]

So for example instead of AnmnFileClassifier I will have ANMNFileClassifier. Just a bit easier to read.

Perhaps update the issue above with that. It makes perfect sense.

[mhidas]

@danfruehauf Done