Value of Comments
28 messages in this thread
Actually… and this may totally raise your eyebrows…
but one of the utilities supplied in the ToolShed package, "cstrip" has no
purpose in the world other than to completely strip comments from a C
program.
There are times, particularly with PD code, when the comments add little
(or actually detract) from the readability of the code. If I find a
programmers comments especially obtuse, I strip them out, run the remaining
text thru our C formatter, and then comment it myself – meaningfully, to
me.
But yes… if a programmer can write w/o comments, and still have right-on
recognition of what's going on (and I find the concept reasonable) then I
see no reason for comments unless it's to be ported by another, shared with
another, and et cetera.
Ben
Amateur Radio Callsign is A A 7 A S
Ben,
I used to be comment crazy and found that they were actually making it
harder for me to follow the flow of the program. I now just comment when I
do things that effect global structures instead of module oriented
variables/structs, well, an occasional one may be needed. But, on the
whole, I started using longer variable names and the code started to
comment itself for the most part.
-jack-
I do think the more structured the code is, the more you comment in FRONT
of a module, and the less you comment IN a module.
Ben
Amateur Radio Callsign is A A 7 A S
I feel better. Ever since I got devkit (which makes commenting easier), I
only comment at the beginning of a function/module, or at critical
statements, and I've started using variable names like, "The_AnimOb_Struct"
<grin> –Eet–
Good man. :^)
Ben
Amateur Radio Callsign is A A 7 A S
I'm glad to hear I'm not the only one doing that. I thought I was just
unable to comment properly inside a routine without causing the code to be
more difficult to read. Sounds like its a common problem.
Marcus
Well, how do you line the buggers (comments) up? <grin> That's what got me
to just comment the beginning of functions. If (in C) the variable names
are explicit enough, then somebody who can read C (well enough to care)
should be able to figure out what the function errr. HOW the function does
what it says it does in the comment at the beginning of the function. I
used to have the very bad habit (desire for 'neatness', I guess) of lining
up my comment deviders… so…
/* this is comment 1 */
/* this is comment 2 */
<shudder> –Eet–
Jim
Explicit isn't enough, the have to be meaningful also.
Victor A. Wagner, Jr.
Oh my <insert personal deity> – I actually agree with you on something 😎
Comments are often wrong/misleading/useless, and I've seen lots of code
where the comments hurt alot more than they've helped. This isn't to say
that all commented code is hard to read, just that some people don't
comment well and would be better off w/out any (or at least not many).
What I really hate are comments like:
foo++; /* Increment foo by 1 */ which serve no purpose but to
clutter up the program.
-Mike
Mike,
Back in the 'early days' I was assigned to the tail end of a project to
add some 'last minute requirements additions'. The entire project (it was
an auto-routing CAD/CAM package for wire-wrap boards) was written in
assembly. Remember, this was the _early_ days…the only HLL we had was
FORTRAN. At any rate, I was handed the listing of the program I would need
to modify (about 2" thick 11" x 14-7/8"). I decided that I would attempt
to derive the mechanism of the auto-routing algorithm by covering the
comments and look only at the 'code'. I had 2 pages of 'listing' open
(maybe 100+ lines) and had been studying it for about 20 minutes when a
pattern finally 'clicked'. I thought I knew what ONE (1) of the
instructions was doing (still in the dark about the entire algorithm tho).
So, I decided to see if my 'guess' was correct. I carefully lifted my
right arm from the listing…and sure enough the comment verified my
conjecture. I was delighted (batting 1 for 1) but decided that maybe I
ought to read the comments since deducing the meaning of 1% of the module
in 20+ minutes was not spectacular progress. Unfortunately, it was the
ONLY comment in the ENTIRE module. I admit to a bit of disappointment at
discovering this as I had just received a light 'reprimand' for _my_ dearth
of comments.
Victor A. Wagner, Jr.
Well comments help alot when they're accurate, and they can save you alot
of time. However, its it not your code how can you know that the comments
are accurate w/out looking at the code? That's the big problem, that you
often can't know how conscientious the author of the code was about keeping
his comments accurate. So you're usually forced to examine the code in
detail anyway. The only time detailed comments work is when you know for
sure that the person who wrote them wrote them well and for a reason, which
is usually not the case.
-Mike
Even when comments aren't totally, 100% accurate, they are still better
than no comments at all. At least one can discern the programmer's state
of mind (what he was trying to do in the section of code), even if the
actual execution differs somewhat. To rely solely on the comments would be
a mistake, but they are of significant value regardless.
I'm still recovering from the last game conversion that I did, where the
original code was written in 68K assembly for the ST. Not a single comment
in the entire source code! Argh! I ended up totally rewriting the sucker
(in C) and used extensive comments (of course). The end result: my
version of the game hit the market just before last XMAS (barely) — the
original version has yet to be published. The author is still trying to
figure out his own code and kill the bugs!
…BobR
I disagree completely. If your comment accuracy percentage is less than
90% or so, you'll never know whether what you're reading in the comments
actually reflects what the code does, or is just the product of a dimented
mind.
Your case is a bit different – in assembly code you really do need more
comments, since you're working at such an incredibly low-level. When
you're working in C, though, most things are pretty self-evident and you
don't have to rely on comments quite as much.
-Mike
Mike,
I don't know about you, but when I'm looking at someone else's code and
trying to totally understand it, I DON'T rely solely on the comments. It's
much too easy to get lulled into a false sense of security. The comments
are useful as a guide, but I never take them as gospel. This is even true
with my own code (particularly if it's not fresh in my mind). I always
assume that the code (and the comments) ARE the product of a demented mind!
If you want to rely solely on the comments, be my guest (and I will try to
keep them accurate for you :-). However, I can assure you that it is
easier (and more productive) debugging the code rather than debugging the
comments. (Or is Manx developing the next generation of debuggers – CDB,
the Comment DeBugger? <grin>)
…BobR
…White Wolf Productions
Huh? The point of my message is that (comments != code) – guess I didn't
make that clear. When I'm looking at code produced by someone I don't
know, I almost always skip the comments entirely and go right to the code
to see what's really going on. The comments usually obscure more than they
illuminate.
-Mike
'C', self-evident. I _never_ in my wildest imaginings have concatenated
those two concepts in the same sentence without a negative. <smmiiille>
Victor A. Wagner, Jr.
I was comparing C to assembly language, not to Pascal. In a C<->asm
comparison, C code is clearly much more self-evident as to what it does
than w/ assembly code. Obviously you can write warped code in C, but the
bulk of C code isn't all that difficult to follow.
-Mike
Mike,
Actually…when going over someone else's code…I love comments.
Mainly because I'm going over it to either fix it…or modify it. At least
with the comments…I know what the programmer was trying to do, and it's a
good place to start debugging.
If the comment says '/* calculate the area of a circle */' and I
see the code is calculating the area of an ellipse…then I've got a clue
that something is amiss.
Don
Yes, but you can run into problems here. What if the programmer actually
wanted to calculate the area of an ellipse, and then a week later went back
on a 'commenting pass', looked briefly at the code, and said 'oh, I guess
this is the area of a circle', and commented it as such. Well, then you're
gonna waste alot of time looking for the 'error ' in the code, when the
only error was in the comment.
The fact is, in most of the code I've seen, there were many more commenting
errors than errors in the source code, because when people update code they
rarely update comments.
-Mike
Mike,
You can run into problems with comments, and without comments. My
experience…having picked up lots of code that was broken, and having to
fix it…is that I'd much prefer having the comments.
Obviously, you must not only look at the comments…you must also
look at the code…and also know what the whole program is supposed to do.
The fact that the comments, and the code don't match is a very good
starting point. Especially when it's in a suspect portion of the program.
Don
I think the main problem is that comments are always an unknown quantity as
far as what the programmer was trying to accomplish. You know, different
people have different styles of commenting (or lack thereof). OTOH, code
is an absolute that you can count on to always tell you the real story.
-Mike
Mike,
You're right…IF the code you're looking at was written by a
semi-competent programmer. Unfortunately, much of the code I get to fix
was written by incompetent programmers. I've literaly cut the source code
just about in half just by re-writing the functions properly…let alone
debugging them.
For example:
a function that was called only ONE place in a program, was called
in the middle of a loop that was executed up to 60,000 times and the
function duplicated 1/2 the code in the calling routine AND duplicated it's
own code based on a range comparison (that could only have been 1 of 2
values).
I stripped the duplicate code, moved the function (what was left of
it) inside the loop, removed the range comparison (which was also done
60,000 times) and replaced it with a flag that was used as an index into an
array so the flag was set with a single range check.
This guy didn't know how to indent, used multiple forms of bracing
didn't use #define's for constants, and every other form of bad programming
you can think of…BUT, he was very liberal with comments. At least with
that…I had a clue as to what he was trying to do. Without the comments
it probably would have been better (and maybe faster) for me to have just
scrapped the whole thing and started from scratch.
With the comments…his code was salvageable. Without them it
would have taken me about 3 or 4 days just to figure out what he was trying
to do…and that's all it would have taken me to write it from scratch.
As it was…it was fixed in 2 days into a working, and efficient
program.
This wasn't an isolated example…it was unfortunately the norm for
quite a while.
Don
Mike,
I think it's incumbent on all programmers these days to write code (and
the associated comments) as if someone ELSE would be reading it. I've
learned that even _I_ am 'someone else' if enough time has passed
<smmiiille>.
For _me_, the ability to use arbitrarily long 'names' is helpful.
The ability to use the SAME name in multiple places (e.g. struct widget
* next ('next' being the name)) is mandatory (and IMHO one of early C's
largest failings…fortunately I've never been saddled with such a
monstrosity).
Strong type checking (in the compiler) has saved me _many_ hours of
debugging and I'm glad to see it added to ANSI C.
As a general rule, I prefer comments ONLY at the beginning of a
function/procedure/whatever (occasionally also attached to the 'line' which
defines a variable).
Victor A. Wagner, Jr.
What about job security? I mean, if anybody can maintain the code, they
don't need you!
Jeff,
If I found a person with that attitude working for me, I would fire
them.
Victor A. Wagner, Jr.
So would I, but what if your working for such a person?
Jeff,
Why, I'd fire my boss <grin>.
Victor A. Wagner, Jr.
I agree totally, and that is how I try to write my code. Would that all
programmers were so conscientious, and maybe the overall quality of
software out there would be better.
-Mike