Re: Why programming is so much more than writing code

You're going to have to support it in the future, document it. At least say *something* about why this block of code exists.

My take on this has always been that good code is self-documenting. There are intrinsic limits, though, to how good some code can be, and in those cases yes: document it. Clearly, early, abundantly.

Comment on Re: Why programming is so much more than writing code

Replies are listed 'Best First'.
Re^2: Why programming is so much more than writing code by bibliophile (Prior) on May 08, 2007 at 14:28 UTC
Self-documenting code is good, yes. Necessary, even. But at best it can only tell you what the code does. Sometimes the why is obvious, sometimes not. A good function name can help, but still.... Personally, I like to see even a one-line blurb on why the function exists. It helps me build (or re-build) that mental map of the system. Something like: `# Data comes back from the DB sorted by x,y,z. # If the user wants a different order, here's where we do it.` [download]	[reply] [d/l]
Re^3: Why programming is so much more than writing code by blazar (Canon) on May 08, 2007 at 16:28 UTC
Personally, I like to see even a one-line blurb on why the function exists. It helps me build (or re-build) that mental map of the system. But of course you're a bibliophile! ;-)	[reply]
Re^4: Why programming is so much more than writing code by bibliophile (Prior) on May 09, 2007 at 13:55 UTC
:-) My secret is out! I do have one beef with code doc/comments... when the author's stated intention doesn't actually match what the code does. Is the comment out of date? Is the code flawed? Which do you start with? Having said that, though, I find that way more often than not, having a why-this-function-exists comment helps more than it hurts. Update: Darn it, I thought I was being all clever and stuff... turns out there's a whole thread dedicated to this topic. :-)	[reply]