[bip] Writing Code that Doesn't Suck

[Brandon King]

Hi Titus,

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.

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?

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.

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)
    * 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.
    * Don't override builtin Python functions or variables (common
      mistake: string = "my string" vs import string)
    * 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.
    * 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.

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.

-Brandon


Titus Brown wrote:
> Hey all,
>
> I've just posted a draft set of suggestions on how to write/publish
> code:
>
> 	http://ivory.idyll.org/blog/sep-07/not-sucking.html
>
> People may find it strange that I focus more on form than on substance:
> that's intentional.  I find that both are necessary, and the substance
> is much harder to get right than the form -- but the form is at least as
> difficult to absorb from the community!
>
> That is, there are plenty of books/posts on how to write code well, but
> there are relatively few guides on how to structure, package, and
> deliver your code to the open source community.  This short list can at
> least provide some simple guidelines.
>
> Comments welcome, of course.
>
> cheers,
> --titus
>
> _______________________________________________
> biology-in-python mailing list
> biology-in-python at lists.idyll.org
> http://lists.idyll.org/listinfo/biology-in-python
>
>