lemming's Journal: How to comment your code

I've developed this habit while coding over the last few years. It started out as plain old laziness, but has slowly turned into something useful. At first, I would be partway through the implementation of a function, and get to a hard-ish point. "Eh," I'd think, "I'll come back to this later." I'd leave a reasonably instructive comment so I could come back to it, then I'd finish writing the rest of the function, assuming that whatever needed to be done was, in fact, done.

Now, that's not really very good. In practice, it didn't turn out to be a problem either, and had the side effect of adding a short description to any piece of code that did something complicated (past some subconcious threshold), without me putting out any explicit effort to do so. Convenient!

Nowadays, this habit has turned into something wonderful. I just wrote the following piece of code:

Damnit, slashdot doesn't allow the "pre" HTML tag, so there's not decent way for me to format the code inline... Clicky me!

Alright, so it's probably hard to understand what's going on out of context (independent of the complete lack of actual code), but trust me, this is fantastic. More and more, when I'm writing any reasonably complex function (the threshold is also shrinking), I start out with a written description of said function in the form of comments, that piece-by-piece grows into actual code.

As another, albiet much less cool detail, I'll frequently break up such a function per comment block--I'll add calls to functions (that don't exist yet) to accomplish the task described in each block, then implement the functions one-by-one. This helps for larger functions, even when the sub-functions aren't reused anywhere--the main function itself reads very easily as a textual description of the algorithm implemented therein.

w00t!