ara.t.howard said:
On Sep 21, 2007, at 8:10 AM, On Web wrote: snip
people need to step back and realize that this is a religious issue not
really related to ruby itself.
Yes, it's nothing to do with ruby, religious issue? I don't think so.
i happen to think comments are a crutch in in any language. here is an
excerpt from the last program i wrote:
snip
i do not think comment can add any clarity to code that's written like
this and, yes, you can do the same in C. that being said i'm (literally)
on crutches now and everyone needs them sometimes - they are not evil -
just crutches. compilers are crutches for not being able to write
assembly code quickly enough.
Well, I don't think the HLL compiler/LLL assembler analogy is right or
elevant here.
I understand that well written code can really reduce the need for comments
and comments can sometimes get in the way of reading the flow of code. The
real judge of whether comments are useful is when someone else who hasn't
written the code has to read it. They may even be new to the problem domain
and programming so what seems obvious to those 'in the zone' might be a
complete mystery to someone else, so comments are helpful in those
circumstances. Then we consider the environment where the code is written.
You might be writing the code, but two years down the line, Sarah will be
trying to make sense of it. Sarah has been told to add some feature to the
code if it's not there already. She's been told it's probably there, but
feature 'x' didn't go live when it should have, so it may already have been
coded, or not. It may just need testing to make sure that feature works. Of
course, you've left the company and changed address and phone number. Worse
still, you quarrelled with your old project manager so aren't minded to
co-operate in helping Sarah know what state the code's in.
If nothing else comments can provide a way of tracing the history of code, a
way of identifying who did what and a way of annotation so that you know
that a particular section of code has been altered to suit a particular
change request or bugfix ("Sarah, we've changed the database and object
model, please alter any code that was introduced for change request 66.9 to
reflect the new changes. Please check with whoever made those changes if you
can.").
So, I agree comments should be kept to a minimum. I don't agree that they
are a crutch - they are important for the working dynamic in an environment
where programmers aren't just developing for themselves. If you were working
in my team, you would be including comments - like it or not.
Paul