[AstroPy] Coding Guidelines draft (comments encouraged)

[Mark Sienkiewicz]

On 7/10/11 1:39 AM, Erik Tollerud wrote:
> http://astropy.wikispaces.com/Astropy+Coding+Guidelines
>
> Feel free to ask questions about or comment on any of these items.

It looks pretty mature already.  Here are various comments:

----

"
# The package should be importable with no dependencies other than the 
Python Standard Library (v2.6), NumPy, SciPy, matplotlib, and components 
already in the core Astronomy library."

    *



I was wondering which "Astronomy" library this refers to and what part 
is "core".

I think it means "core Astropy", and I think later it defines "core 
Astropy" as any package that has already been accepted into astropy as 
astropy.whatever;  If this is correct, I recommend "in the core 
Astronomy library" -> "already in the Astropy package".

----

I recommend that the template package include some small amount of C 
code and the Cython example for how to use it.

I note that the Cython recommendation implies an additional external 
dependency for somebody.  Is this for anybody who installs Astropy from 
source, or is it a preprocessor that you only run occasionally like 
yacc/lex?

----


"

    * If an external C library is needed, the source code for the
      library should be bundled with the astropy core. Additionally, the
      package must be compatible with using a system-installed library
      instead of the version included in astropy."


add "... using the mechanism shown in the template package."

We want everybody to provide the same flags, same interface, etc, so we 
show one way to do it and ask everybody to do it that way.


----

If you want to require PEP 8, I suggest that you make your examples PEP 
8 compliant.

----

I think we should explicitly recommend the new relative import mechanism 
any time you import another module/package that is in the same package 
you are part of.

Say, for example, that you want to debug a package and you would like to 
run both the original and a modified copy at the same time.  With 
relative imports, you don't need to edit every import line in the whole 
package to make your modified copy.

This is not compliant with PEP 8, which recommends the bad practice of 
always using absolute imports.  It made sense when relative imports were 
ambiguous, but the Python language no longer has that particular weakness.

----

The property/get/set example is weak:  1) Take out the functions that 
are not relevant to get/set; you don't need them cluttering the 
example.  2) Show a user interacting with the object:

     x = star()

     # use this
     x.color = 100
     print x.color

     # not this
     x.set_color(100)
     print x.get_color()

Realistically, I think people are likely to want to use the 
get_color()/set_color() approach because it is more natural.  It also 
makes it more clear what is happening.  I know that hard core OO guys 
think properties are cool, but I've never seen the attraction myself.

----

The super() example actually shows more instances of doing it the wrong 
way than the right way, and it does not clearly mark which one to use.

It should show one complete implementation using super() [marked "don't 
do this"] and another complete implementation using direct calls [marked 
"do this"].

One of the common cases for wanting to call into the superclass is to 
invoke the __init__() method.  The example should show how to do this, 
including the case of multiple inheritance.

----

In the "import *" example, "__init__" is shown as "init" (two places).  
It looks like it needs a wiki escape.