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

[bibliophile]

in reply to Re: Why programming is so much more than writing code
in thread 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.

[blazar]

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

[bibliophile]

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