sfepy/sfepy — Issue #47: let's use python style guidelines
Author: rc
Created: 2012-01-30 10:24:45+00:00
State: open

Let's make sfepy a regular python library by following the usual
conventions that people expect in python.

Mainly this:

http://www.python.org/dev/peps/pep-0008/

"
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.
"

Currently, sfepy uses both

some_method()
someMethod()

this is very inconsistent. I am not even mentioning things like the
following :)

dm_printNeighbourList()

From the guidelines:

"
Function Names

Function names should be lowercase, with words separated by underscores
as necessary to improve readability.

mixedCase is allowed only in contexts where that's already the
prevailing style (e.g. threading.py), to retain backwards compatibility.

[...]

Method Names and Instance Variables

Use the function naming rules: lowercase with words separated by
underscores as necessary to improve readability.
"

So I think the whole sfepy should just use one style overall. Let's use the
style that is suggested in the guidelines. (We don't have to be a backwards
compatible yet like threading.py)

Migrated from http://code.google.com/p/sfepy/issues/detail?id=43

earlier comments

robert.cimrman said, at 2008-06-26T11:52:29.000Z:

ok, as numpy and scipy have also tried to stick to it recently. Just one thing I
would like to preserve in SfePy:

function( x, y, z )
instead of
function(x, y, z)

The two extra spaces improve the readability quite a bit, as the arguments are
visually separated from function name.

Any volunteers to automate this?

ondrej.certik said, at 2008-06-26T11:56:03.000Z:

I don't think it can be automated. I'll provide a patch that fixes all the names.
I'll look at how this could be done easily in vim, or some commandline script.

robert.cimrman said, at 2008-06-26T12:08:00.000Z:

yep. some IDE with refactoring should be able to do it, e.g. emacs (or vim :)

ondrej.certik said, at 2008-07-16T11:54:14.000Z:

This is a release blocker.

robert.cimrman said, at 2008-07-16T12:47:06.000Z:

I propose additional recommendations:

- do not use single letter names (not even loop variables - use e.g. ii, ir, ic, ...)
- prefer whole words to abbreviations in public APIs - there is completion after all
yes: equation, transform_variables(), filename
rather not: eq, transvar(), fname
- functions have usually form _()
e.g.: save_data(), transform_variables(), do not use data_save(),
variable_transform() etc.
- variables like V, c, A, b, x should be tolerated only locally when expressing
mathematical ideas
- I like more function( arg1, arg2, arg3 = value ) than
function(arg1, arg2, arg3=value)
- a = 1 instead of a=1
- some more?

comments?

ondrej.certik said, at 2008-07-16T14:10:43.000Z:

I agree, except:

- do not use single letter names (not even loop variables - use e.g. ii, ir, ic, ...)

I prefer to use single letter loop variables when appropriate.

- I like more function( arg1, arg2, arg3 = value ) than
function(arg1, arg2, arg3=value)

I like more function(arg1, arg2, arg3=value), simply because this is what other
people use, so that's what I am used to.

otherwise ok.

Whenever you have something that doesn't follow the mainstream you really need to
have a good reason for it, otherwise it just looks unprofessional and it's more
difficult for other people to read the code. And we need more python developers,
rather than creating obstacles for them. imho.

robert.cimrman said, at 2008-07-16T14:24:06.000Z:

Single letter loops are ok, its just that finding (in an editor) a single letter in
text is difficult as it tends to be included in many other words.

Random remarks:
As for fun( arg ) x fun(arg) it's just whitespace but in the latter form fun and arg
are not visually separated and I find it difficult to read.

fun(a,b,c,d) or fun( a, b, c, d ) are self-consistent, fun(a, b, c, d) is not, IMHO.

Anyway those were meant as recommendations, not rules.

Btw. for renaming I am going to use http://bicyclerepair.sourceforge.net/ within Emacs.

ondrej.certik said, at 2008-07-16T14:49:26.000Z:

> Single letter loops are ok, its just that finding (in an editor) a single letter in
> text is difficult as it tends to be included in many other words.

Good editors allow you to search for the word "i", in vim it's the command "*".

> As for fun( arg ) x fun(arg) it's just whitespace but in the latter form fun and
> arg are not visually separated and I find it difficult to read.

I understand your argument, but I think it's a matter of habit. My argument is above.

> fun(a,b,c,d) or fun( a, b, c, d ) are self-consistent, fun(a, b, c, d) is not, IMHO.

My rule is to use a space after ",", so f(a, b, c) is perfectly consistent, while the
others are not. :)

robert.cimrman said, at 2008-07-16T14:55:27.000Z:

Sometimes you have not good editor. But enough - this one is settled.

Yeah, habits. I will have enough problems with getting used to new function names
that I reserve myself the right to call( a, function, this, way ). :)

ondrej.certik said, at 2008-07-16T15:02:06.000Z:

> Yeah, habits. I will have enough problems with getting used to new function names
> that I reserve myself the right to call( a, function, this, way ). :)

Sure. I can live with this minor problem for some time. :)

ondrej.certik said, at 2008-07-21T12:49:10.000Z:

Ok, one last problem is the call( a, function, this, way ) stuff. But we agreed to go
with it for some time.

BTW, do you require me to use it as well? If I find a free while, I can try to craft
some script that will do the call(a, b, c) <---> call( a, b, c ) transformations
automatically and correctly.

Anyway, this issue is mostly fixed, so I am lowering the priority to medium.

robert.cimrman said, at 2008-07-21T12:59:14.000Z:

Certainly call( a, b, c ) is easier to parse as you can just use split() :)

IMHO we have now better things to do than writing scripts that remove/add two spaces
- this is a non-issue.

I would prefer if you use also call( a, b, c ) for future stuff, but it is just a
recommendation, just like the others proposed in comment 5.

ondrej.certik said, at 2008-07-21T15:44:33.000Z:

Agree. As long as we will not reject code with one or the other style, it's ok with
me. It's a huge improvement over the former state. :)

robert.cimrman said, at 2008-07-21T15:53:15.000Z:

IMHO we could close this general issue, and eventually submit more specific ones
related to this topic, e.g. filename vs. file_name.

ondrej.certik said, at 2008-07-21T17:53:46.000Z:

Yep.