let's use python style guidelines

[GoogleCodeExporter]

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)

Original issue reported on code.google.com by ondrej.c...@gmail.com on 26 Jun 2008 at 11:28

[GoogleCodeExporter]

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?

Original comment by robert.c...@gmail.com on 26 Jun 2008 at 11:52

[GoogleCodeExporter]

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.

Original comment by ondrej.c...@gmail.com on 26 Jun 2008 at 11:56

[GoogleCodeExporter]

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

Original comment by robert.c...@gmail.com on 26 Jun 2008 at 12:08

[GoogleCodeExporter]

This is a release blocker.

Original comment by ondrej.c...@gmail.com on 16 Jul 2008 at 11:54

• Added labels: Priority-High
• Removed labels: Priority-Medium

[GoogleCodeExporter]

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 <action>_<subject>()
  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?

Original comment by robert.c...@gmail.com on 16 Jul 2008 at 12:47

[GoogleCodeExporter]

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.

Original comment by ondrej.c...@gmail.com on 16 Jul 2008 at 2:10

[GoogleCodeExporter]

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.

Original comment by robert.c...@gmail.com on 16 Jul 2008 at 2:24

[GoogleCodeExporter]

> 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. :)

Original comment by ondrej.c...@gmail.com on 16 Jul 2008 at 2:49

[GoogleCodeExporter]

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 ). :)

Original comment by robert.c...@gmail.com on 16 Jul 2008 at 2:55

[GoogleCodeExporter]

> 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. :)

Original comment by ondrej.c...@gmail.com on 16 Jul 2008 at 3:02

[GoogleCodeExporter]

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.

Original comment by ondrej.c...@gmail.com on 21 Jul 2008 at 12:49

• Added labels: Priority-Medium
• Removed labels: Priority-High

[GoogleCodeExporter]

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.

Original comment by robert.c...@gmail.com on 21 Jul 2008 at 12:59

[GoogleCodeExporter]

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. :)

Original comment by ondrej.c...@gmail.com on 21 Jul 2008 at 3:44

[GoogleCodeExporter]

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

Original comment by robert.c...@gmail.com on 21 Jul 2008 at 3:53

[GoogleCodeExporter]

Yep.

Original comment by ondrej.c...@gmail.com on 21 Jul 2008 at 5:53

• Changed state: Fixed

[GoogleCodeExporter]

Migrated to http://github.com/sfepy/sfepy/issues/47

Original comment by robert.c...@gmail.com on 30 Jan 2012 at 10:24

• Changed state: Migrated