[bip] Writing Code that Doesn't Suck
Brandon King
kingb at caltech.edu
Tue Sep 25 13:08:10 PDT 2007
Titus Brown wrote:
> -> I think you're off to a great start and that this document is likely to
> -> become very useful. I assume you will be adding more substance in the
> -> near future? I can see how each one of the topics could have one or more
> -> tutorials. Depending how far you take this, I might end up contributing.
>
> Perhaps keep this document as a short intro, and then link to more
> detailed pages with examples? I don't like overwhelming people with
> more than a page or two of material when I'm trying to get them to
> change practices ;)
>
I like that idea and completely agree. By the way, do you want to make
another revision of the document before posting it on bio.scipy.org?
Maybe we should create stubs to the examples to encourage contributions?
> -> By the way, maybe I did not read the document carefully enough, but it
> -> seemed like "Use docstrings" was referred to indirectly rather than
> -> explicitly said?
>
> Indeed.
>
> -> And, what about adding a section on documentation? There's nothing worse
> -> than great piece of code that only a few people know how to use, because
> -> of a lack of documentation. A "getting started tutorial" or small
> -> examples + API docs can go a long way. Ok, I can ramble about
> -> documentation, so I think I will only post more of my thoughts if it is
> -> requested.
>
> Indeed.
>
> -> Some "What not to do!" sections could be useful as well. Such as (just
> -> some ideas off the top of my head to get people thinking):
> ->
> -> * Don't change the API w/o a change log if you have users (not much
> -> of an issue if you are the only user)
>
> Yes.
>
> -> * Don't tell people to get your code from revision control while you
> -> leave "stable" release on your website which is 2 years old, and
> -> your SVN copy is more "stable" than the old release.
>
> Heh, yes.
>
> -> * Don't override builtin Python functions or variables (common
> -> mistake: string = "my string" vs import string)
>
> Yes.
>
> -> * Make releases with name <package_name>-current.tar.gz; use
> -> <package_name>-<date or rev_number>.tar.gz instead. When someone
> -> finds <package_name>-current.tar.gz sitting on their hard drive,
> -> how current is it really? What version number is it? What if this
> -> is the only version that currently works and you need to provide
> -> the world, paper, college, etc. with what version to use. Simple
> -> change, can make a difference.
>
> Ahh yes, and also for packaging, make sure that it unpacks into an
> obvious subdirectory name, e.g.
>
> package-5.2.tar.gz => package-5.2/
>
> -> * Don't invent your own file format without documenting it and
> -> including a version number in a comment.
> -> o Don't change your file format without documenting the
> -> changes and upping the version number.
>
> heh, yes.
>
> -> Ok, that's probably enough examples for now. Some of those may not be
> -> that important. Maybe this should be it's own "What not to do guide"?
> -> Food for thought.
>
> These seem like good things to add; thanks for the comments! I'll add
> you on as author (although, to be honest, I was assuming that this would
> become an authorless document on the wiki... but it's not a bad idea to
> add "whom to blame" on to it).
>
Your welcome, and thanks for writing this document. You can always add a
"contributions by" section as an alternative to an "author list". In
general that might be a good idea for the tutorials, etc. Having the
original author at the top, and then contributers list below, so people
know they are welcome to make contributions?
> Incidentally, the Cheesecake project might check for some of these
> things already (docstrings, proper unpacking, easy_installable, etc.).
> I should go look at that...
>
> --titus
>
>
More information about the biology-in-python
mailing list