[bip] Writing Code that Doesn't Suck

[Titus Brown]

-> 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 ;)

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

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