Thanks. If I expect a piece of code to survive any length of time I try to document it well because I tend to forget how/why I decided to do things. In that piece of code, I knew that I'd forget the trig. part quite quickly so I figured an ASCII diagram was needed.

If you enjoyed that piece of code you might also enjoy the C code linked here: http://blog.jgc.org/2008/02/tonight-im-going-to-write-myself...

Perhaps there should be a 'beautiful code' blog as a sort of counterpart to the Daily WTF. I could reuse the domain usethesource.com.

Update: An there it is UseTheSource (http://news.usethesource.com/news). Submit examples of beautiful or interesting code.

Awesome! I hate seeing people say "Make good comments, not like X". I have given up on asking "what would be a good comment" because no one seems to be able to point to a good example. This will be much helpful :).

I really don't think news.arc is a good medium for something like this -- you might as well have hosted it using an Enterprise CRM.

Really? So if a fundamental assumption changes in the code you'll be happy to make a 3 line change and rewrite 10 pages of documentation inline?

Personally I like the code to be as self documenting as possible about the "what", the check ins to be as explicit as possibly about the "why" (and "who" and "when") and documentation for architectural information ("where").

While I agree with your second paragraph, I have to say that yes, I'd be happy to rewrite inline documentation to reflect a 3-line code change. Ten pages of inline documentation is a lot and probably inappropriately located, but if it really takes ten pages to describe what three lines of code are doing, there is just no way those three lines of code can be self-documenting. (So much for extreme examples...)

As you mentioned, there are different places for documentation: inline, commit comments, change tracking system, project/release planning documents, and overall system architecture documents. These all serve different purposes, describe different aspects, and typically have different audiences. They all have different levels of detail too. The code itself is the most detailed documentation, because it describes what the software actually does when it runs, and should be as readable as possible. The inline comments supplement that, because the code describes "what" but not "why". You mention that check ins should describe "why", but they give the why for the overall change, not for each block of code. Inline comments give the why for each block of code.