[AstroPy] Coding Guidelines draft (comments encouraged)

[Erik Tollerud]

> I know people have been busy, myself included, but I wonder if anyone
> has had time to consider the use of super() and the defense thereof.

Based on the lack of further discussion on the top, it would seem not :)

> I would change the coding guidelines read opposite of how they do
> currently: Use of super() should be encouraged except where one knows
> for sure that it's not going to be appropriate, due to the need for a
> customized method resolution order.  What *should* be discouraged is the
> use of multiple inheritance except in the cases of orthogonal bases, or
> if one is really sure what they're doing.

You raise some very good points - my main concern was that it always
be consistently super() or consistently not . I can see that use of
super() would be a safer guideline given these use cases - does anyone
object to this?

If not (within a few days,hopefully), I will update the guidelines to
suggest using super() unless there is a specific reason not to (and
require that it be specifically mentioned if so), as well as
discouraging multiple inheritance without a good reason (and replace
the old example with an orthogonal base/mixin example that uses
super()).


> On an unrelated matter, I have one other suggestion for the coding
> guidelines:
>
> A top level package's __init__.py should be importable under all
> circumstances, and should not too much "stuff" in it, for lack of a
> better word.  To explain: Several of our own packages have an
> __init__.py that contains a lot of functionality, such that when I try
> to import it, it might crash (due to some prerequisite not being met),
> take a very long time (due to it importing many submodules
> unnecessarily), or it might have actual side effects like writing to the
> filesystem.
>
> All of these behaviors should be discouraged.  In particular it can
> cause problems for installation and test frameworks which use the Python
> import mechanism to discover packages and modules on the path.  Merely
> importing the package should not fail due to, for example, an
> environment variable not being set.
>
> There are valid reasons for the __init__.py containing functionality, in
> particular for ease of use at the Python command line.  But they should
> be designed so that they can at least be imported without side-effects.
>  This would mean cleanly disabling certain functionality if any
> prerequisites are not bet, and delaying any side-effects until it's
> certain that they are necessary.
>
> Just to give a concrete example (that's long since been fixed, actually)
> matplotlib used to try to write out a default cache/config directory
> upon import, which could fail if the process it was running in didn't
> have permission to create that directory.  That's the kind of thing that
> should be avoided.  I think that a note to that effect should be added
> to the coding guidelines.  I'd be happy to write up a draft if people
> agree with this.

Sounds good to me - feel free to write up such a note and submit it
either in github pull request form or just on this mailing list.



-- 
Erik Tollerud