

Comments In Code - hamedh
http://hamedh.posterous.com/comments-in-code

======
DrPppr242
I signed up for an account just to say I strongly disagree with this. I'm a
sys admin who doesn't spend all day writing code, and certainly doesn't know
all the common idioms associated with different languages. Leaving a comment
about in the code about something that's not obvious to some one who doesn't
code in perl/ruby/php (or whatever you're using) but if familiar with common
programming concepts is beyond useful to someone like me.

------
jcmhn
Why I comment:

When I'm learning a language I write comments for myself. Notes about syntax,
idioms, gotchas, and whatever else.

When I'm fixing a problem I leave XXX markers around to easily keep track of
what I'm doing.

When I'm writing maintenance code I reference the ticket number, describe the
problem or feature, and why we implemented the fix or feature the way we did.

You should never see the first two types of comments in checked in code, but I
bet that I've probably saved later maintenance programmers hours of
frustration with that last type of comment.

------
chrisledet
I'll just leave this here: <http://zachholman.com/posts/documentation/>

~~~
hamedh
Yea, good post, I agree that documentation is key.

------
beaumartinez
Comments and readable code aren't mutually exclusive.

> _Code should be almost as readable as a book. You should be to read without
> pausing too much as well as skimming._

I pause much more reading code than I do reading prose.

Trying to keep a lookup table of functions and variables in my head is much
harder than reading a few lines of prose to let me know what's going on.

Comments should summarise what's going on, so that when you have a bug, you
can jump to the right section to change.

> _Comments are almost like an annotation in a book. So use them sparingly._

The way I think of it: Don't use comments to annotate your code. Use code to
annotate your comments.

------
gordonguthrie
I agree - it is the old principle of least surprise. You should use comments
when the code reader would be surprised...

Sometimes you _have to_ do bad stuff and you should stick a comment in there
so that when you come back to that bit in code you are forewarned...

Think of it as _hic seunt leones_ on old maps (here be lions for all the non-
latin speakers out there...)

------
baggachipz
Don't like my comments in my code? Don't read 'em. They're useful to some
people.

------
ascendant
This discussion is one that will never die because people will always have
entrenched, dogmatic viewpoints on this. I dislike comments that explain what
you're doing. The code should be readable enough to see what you're doing.
However having spent over a decade now maintaining code written by people that
may not be with the organization anymore, it's always nice to occasionally get
context on WHY someone wrote the code they did. Odd bugs and subsequent
workarounds, weird client requirements, etc. I've spent many hours trying to
figure out why someone did something because they're not around anymore to
ask. We can go on and on about the purity of code and how readable it should
be but no amount of concise code can replace "did this because of client
requirement X,Y and Z" right there so I don't have to go hunting to find out.
The gulf between how things SHOULD be and how they ACTUALLY are is pretty wide
in my experience.

~~~
endeavor
I think parent's import point is that comments should document WHY you are
doing something. The code itself should easily convey the WHAT and HOW.

"Programs must be written for people to read, and only incidentally for
machines to execute." - <http://mitpress.mit.edu/sicp/front/node3.html>

