Re^2: Why programming is so much more than writing code

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]

Comment on Re^2: Why programming is so much more than writing code Download Code

Replies are listed 'Best First'.
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]