Commenting the source code.

[Profetas]

Hi,

I know that this is off topic. but I didn't know
where to post.

Do you comment your source code while coding or after coding.

for example:

you write a procedure and after it is working, you'll comment it.

or

you write a line of code and a comment following.
Thanks Profetas

[Joona I Palaste]

Profetas <xu*****@yahoo.com> scribbled the following:

Hi, I know that this is off topic. but I didn't know
where to post. Do you comment your source code while coding or after coding. for example: you write a procedure and after it is working, you'll comment it. or you write a line of code and a comment following.

I generally add a comment every time I finish a piece of code that does
some non-trivial task. I don't have any rules based on actual LOC
metrics but instead count the things that my code actually does, on a
semantic level. Sometimes I write several pieces of code into a single
source file, and only later comment them all, one by one.

--
/-- Joona Palaste (pa*****@cc.helsinki.fi) ------------- Finland --------\
\-------------------------------------------------------- rules! --------/
"Hasta la Vista, Abie!"
- Bart Simpson

[dandelion]

"Profetas" <xu*****@yahoo.com> wrote in message
news:ca******************************@localhost.ta lkaboutprogramming.com...

Hi,

I know that this is off topic. but I didn't know
where to post.

Do you comment your source code while coding or after coding.

Sometimes i'll comment after coding.

Sometimes ill comment whilst coding.

Sometimes i'll comment before coding as a "pseudolanguage" to-do-list or
providing a nice general explaination of the algorithm(s) used, pitfalls and
solutions, quirks, oddities and general notes.

As long as the comments are there...

[Rob Thorpe]

"Profetas" <xu*****@yahoo.com> wrote in message news:<ca******************************@localhost.t alkaboutprogramming.com>...

Hi,

I know that this is off topic. but I didn't know
where to post.

Do you comment your source code while coding or after coding.

for example:

you write a procedure and after it is working, you'll comment it.

or

you write a line of code and a comment following.
Thanks Profetas

When write a function I write comments above lines that I think need
them. Later I write a comment that describes the purpose of the whole
function, but I don't do that until after it's done and mostly
integrated because the purpose normally changes slightly when this
happens.

[Profetas]

Thanks for the reply.

My theory is that commenting whilst you are coding,
will break your concentration on what you were programming.

If it is something complex.
Does anybody agree?

Profetas

[Thomas Stegen]

Profetas wrote:

Thanks for the reply.

My theory is that commenting whilst you are coding,
will break your concentration on what you were programming.

If it is something complex.

Does anybody agree?

Not me. My two main points about comments.

1) If something low level needs a comment you are only solving the
symptom, not the problem. Is this absolute? No. Sometimes you need
obscure code for performance issues, though sometimes second guessing
the optimizer kills it. Keyword: Think.
2) Comment the abstraction a function is meant to represent, document
the pre and post conditions, arguments, range, domain and side
effects. Keywords: Detail without verbosity.
And then you have everything else to consider.

--
Thomas.

[Alan Balmer]

On Fri, 22 Oct 2004 06:23:28 -0400, "Profetas" <xu*****@yahoo.com>
wrote:

Hi,

I know that this is off topic. but I didn't know
where to post.

Do you comment your source code while coding or after coding.

for example:

you write a procedure and after it is working, you'll comment it.

or

you write a line of code and a comment following.

Before, during, and after :-)

Sometimes I'll write a comment before a block of code to make sure I
have my thoughts in order and know where I'm going. I write comments
as needed during coding, and after coding, I review to see if there
are any clever things I've done in the heat of the moment that I won't
understand next week.

--
Al Balmer
Balmer Consulting
re************************@att.net

[Herbert Rosenau]

On Fri, 22 Oct 2004 10:23:28 UTC, "Profetas" <xu*****@yahoo.com>
wrote:

Hi,

I know that this is off topic. but I didn't know
where to post.

Do you comment your source code while coding or after coding.

for example:

you write a procedure and after it is working, you'll comment it.

or

you write a line of code and a comment following.

I follow these rules:
- design the whole program
- break down the design to be more specific
- break down each specific design to be more specific
repeat until each problem is broken into peaces lttle enough
to fill only a screen or a bit more
build modules holding a sub problem (of a sub problem....)
check anything. Recheck it again to be sure to have no mistake in
the design
- design the interfaces
even no coding - only design
recheck that them match any request, change if needed
- document anything well

- start filling modules with documented interfaces and empty function
definitions.
let any trunc return one error result (NULL pointer when it has to
return a pinter in result, anything else that presents an error in
other cases)
insert an debug functiion that says that the function is not
realised yet
This gives you the possibility to start
- build the headers and document them
- build the makefile and document it
test the makefile
- write, document, compile and debug debug fuctions.
You needs debugged debug functions to get your debug sessions more
successfully. Whereas successfull means dedect bugs, checks the
wanted results occure.

Now the project can change in its coding phase
- code, low level fuctions
- comment anything logically
that means write comments relayed to the logical funtionality
but NOT to the coding
- check the comment as if it were code for correctness in logic and
flow
correct errors now!
- when the comments are perfect fill each comment (section)
with the matching code. Use the makefile to to test for errors in
typing.
- write short testcase to debug each function. Neends no great
comments as they
are used only temporary to test the fuctions for korrectness
This ends up with well tested very, very low level fuctions. You
knows
that each function does anything as espected - including failture
handling.
- restart at top of this section but one logical level higher
while testing you can use the lower level functions without testing
them
because the prior cycle has done that careful, so bugs are only in
the new code.

Comments are essential for
- finding design bugs before the first code line gets written
- finding bugs while coding (that is why your comment is on logical,
not
coding level anyway
- finding bugs while debugging. Each programmer gets sometimes a bit
crazy
and writes code other than the design says you should.

True, yes, designing of the whole program and all its lower leveled
functions costs a lot of time. But at least spending one day for the
design and checking it saves you a full week and more on coding and a
month on debugging. So spend any time you needs to get your design
perfect. You saves a multiple time of that in coding.

Debug each little fuction extensive. It is your time you wins. Test
each function separately before you goes to the next one. That is
because you can use it later without doubt of an bug inside it. So you
gets higher level functions more quick ready for use.
--
Tschau/Bye
Herbert

Visit http://www.ecomstation.de the home of german eComStation

[Eric Sosman]

Profetas wrote:

Thanks for the reply.

My theory is that commenting whilst you are coding,
will break your concentration on what you were programming.

If it is something complex.

Does anybody agree?

Not I. If your understanding of what you are doing
is so tenuous that it can't survive the attempt to write
it down, the chances that your understanding is correct
to begin with are poor. Brian Kernighan says "Debugging
is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible,
you are, by definition, not smart enough to debug it.”
I take that as strong advice against writing code at the
limits of your comprehension.

Personally (and this is only a matter of taste), I
like to give each function a block comment describing its
purpose, and I write this comment before writing the code.
I also like to put line-by-line comments on important data
structures and variables, and I tend to write those as I
write the declarations. And that's about it: I'll sometimes
go back after the fact and add comments for anything that's
tricky or unclear or unusual, but since I try to follow
Kernighan's advice such comments are pretty rare.

--
Er*********@sun.com

[John Bode]

"Profetas" <xu*****@yahoo.com> wrote in message news:<ca******************************@localhost.t alkaboutprogramming.com>...

Hi,

I know that this is off topic. but I didn't know
where to post.

Do you comment your source code while coding or after coding.

for example:

you write a procedure and after it is working, you'll comment it.

or

you write a line of code and a comment following.
Thanks Profetas

Depends on what I'm writing and who I'm working for at the time. Some
companies have fairly strict documentation standards. Many don't.

If I'm creating a new file, there's usually a template that I work
from. I copy the template, modify the header as required, then start
writing code. When I'm creating a new procedure, I first create the
doc header for it (name, inputs, outputs, returns, etc., as dictated
by the standards of whomever I'm working for at the time), then write
the procedure body. Within the procedure body, I'll usually write all
the code without stopping, then go back and comment where necessary.
If I'm fixing a defect, I'll first insert a comment with the defect
tracking number, then add the fix, then go back and add to the comment
if necessary (although usually, details of the fix are documented in
the CM and defect tracking tools, not the source -- you can use the CM
tool to view the actual code changes).

[Michael B Allen]

On Fri, 22 Oct 2004 06:23:28 -0400, Profetas wrote:

Do you comment your source code while coding or after coding.

Aside from what other folks said I want to point out that many people,
including myself, greatly dislike huge block comments like:

/************************************************** ***********
* This is a HUGE stupid comment. Can you tell?
*
************************************************** ***********/

You might think this is obviously wrong but believe me when I tell you it
happends far too often. I purchased a book once called "Data Structures
and Algorithms in C" (or something like that) that has HUGE blocks of
comments that were crazier than the above. I felt pretty stupid afterward
for not looking closer at it.

As others have advocated I too much prefer seletive comments. A
particularly nice non-intrusive technique is to use something like the
below with little right-justified annotations to walk the reader through
the code:

....
if (c2 > c1) { /* append to end of list */
if (ISADJ(c1,c2)) { /* join with last cell */
c1->size += POFF + c2->size;
return 0;
}
c2->next = c1->next;
suba->tail = c1->next = ref;

return 0;
}

while (c1->next < ref) { /* find insertion point */
c1 = SADR(suba, c1->next);
}
c3 = SADR(suba, c1->next);

j1 = ISADJ(c1,c2); /* c1 and c2 need to be joined */
j2 = ISADJ(c2,c3); /* c2 and c3 need to be joined */

if (j1) {
if (j2) { /* splice all three cells together */
if (SREF(suba, c3) == suba->tail) {
suba->tail = SREF(suba, c1);
....

Mike

[Jason Whitehurst]

Profetas wrote:

My theory is that commenting whilst you are coding,
will break your concentration on what you were programming.
If it is something complex.
Does anybody agree?

Completely disagree.

Commenting the line may help you to formulate your thoughts to understand
exactly what you are coding. You may find, while writing the comment, that
there is a much easier, more efficient, whatever way to code it - and not
waste time coding it twice.

--
Jason

[Neil Kurzman]

Profetas wrote:

Thanks for the reply.

My theory is that commenting whilst you are coding,
will break your concentration on what you were programming.

If it is something complex.

Does anybody agree?

Profetas

No one really comments afterward. they just say they will, but there is
never time.

[Malcolm]

"Profetas" <xu*****@yahoo.com> wrote

My theory is that commenting whilst you are coding,
will break your concentration on what you were programming.

If it is something complex.

Does anybody agree?

Yes. Comments are for people, including you after some time, who need to
look at the code after it is finished. If you put in comments during actual
writing you may need to take them out, you may find it hard to "comment out"
code, and, worst of all, you may invalidate a comment and forget to change
it, something no compiler can catch.
Also, as you say, writing comments may take your attention from the actual
code. People will differ in this, but certainly if someone has imposed a
very burdensome commenting regime on you then it may slow you down
considerably if you try comment as you code.
I am not absolutely systematic, but normally I write code in modules without
comments. Then I test it. When the module is "ready" I put in comments
saying what all the functions do and how to call them. If it is presentation
code I might also comment non-obvious lines (eg "BMP files begin with
letters BM", or "sign extend"), generally I also comment structure members.

[Simon]

"Profetas" <xu*****@yahoo.com> wrote:

I know that this is off topic. but I didn't know
where to post.

Do you comment your source code while coding or after coding.

for example:

you write a procedure and after it is working, you'll comment it.

or

you write a line of code and a comment following.

Comments are for script-kiddy Visual BASIC programmers. Real men
don't comment code: if it was hard to write it should be hard to
understand.

[Joona I Palaste]

Malcolm <ma*****@55bank.freeserve.co.uk> scribbled the following:

"Profetas" <xu*****@yahoo.com> wrote

My theory is that commenting whilst you are coding,
will break your concentration on what you were programming.

If it is something complex.

Does anybody agree?

Yes. Comments are for people, including you after some time, who need to
look at the code after it is finished. If you put in comments during actual
writing you may need to take them out, you may find it hard to "comment out"
code, and, worst of all, you may invalidate a comment and forget to change
it, something no compiler can catch.

One of our source files over at work is rife with comments about some
obscure kludges that had to be inserted and need to be removed in the
future. But over the course of the program's development, no one has
bothered to find out what these kludges exactly are, which part of the
code they affect, and how (or if) they can be removed. So the file still
has comments about "This kludge should be removed by version n" when
we're already in version n+2. Actually the whole file needs complete
replacing but no one has got around to designing a replacement.

--
/-- Joona Palaste (pa*****@cc.helsinki.fi) ------------- Finland --------\
\-------------------------------------------------------- rules! --------/
"I said 'play as you've never played before', not 'play as IF you've never
played before'!"
- Andy Capp

[Peter Shaggy Haywood]

Groovy hepcat Profetas was jivin' on Fri, 22 Oct 2004 11:40:15 -0400
in comp.lang.c.
Re: Commenting the source code.'s a cool scene! Dig it!

My theory is that commenting whilst you are coding,
will break your concentration on what you were programming.
If it is something complex.
Does anybody agree?

Someone might, someplace in the World. But I don't.
Comments often help me concentrate on what I'm doing. Keep them
simple, short and to the point. Don't try to explain how a whole 500
line function works, in detail, in a single comment, otherwise you
will get distracted. But writing helpful comments along the way makes
coding easier.

--

Dig the even newer still, yet more improved, sig!

http://alphalink.com.au/~phaywood/
"Ain't I'm a dog?" - Ronny Self, Ain't I'm a Dog, written by G. Sherry & W. Walker.
I know it's not "technically correct" English; but since when was rock & roll "technically correct"?

[Peter Shaggy Haywood]

Groovy hepcat Profetas was jivin' on Fri, 22 Oct 2004 06:23:28 -0400
in comp.lang.c.
Commenting the source code.'s a cool scene! Dig it!

I know that this is off topic. but I didn't know
where to post.
Do you not get comp.programming?
Do you comment your source code while coding or after coding.
Yes.
No, seriously, I usually write comments before, during and after I
write the code.
I often write comments before I start writing the code, to give me a
good idea of what the code should do. I make these comments clear and
concise. They clearly set out each step of the algorythm/procedure to
be used. Then I write code to implement those steps.
Of course, there are always times when you look at some code after
you've written it and think that a comment would help explain some
part of the code or the reason for some weird-looking workaround. You
may have thought it was obvious before, and changed your mind when you
had to re-read the code months later, or even minutes later.
The rest of the time, it just makes sense to comment as you go. You
write down what you're doing and why. You do it before you forget.
for example:
you write a procedure and after it is working, you'll comment it.
No. That's not the best way to go. By the time you've got something
working you may have forgotten how you got it working, all the things
you tried. Comment as you go. If you make changes that affect the
accuracy of the comments, change the comments as you change the code.
or
you write a line of code and a comment following.

Most of my comments precede the lines of code they explain. They
explain the intent of a group of logically linked statements. Some
comments, however, go at the ends of lines - short comments at the
ends of short lines. These are somewhat along the lines of labeling.
A comment for each and every line of code is excessive. You should
comment every group of lines, where a group performs some single part
or step of the procedure to be performed. Comment each step, not each
line. And even then, don't comment what is absoulutely, blatantly
obvious.

--

Dig the even newer still, yet more improved, sig!

http://alphalink.com.au/~phaywood/
"Ain't I'm a dog?" - Ronny Self, Ain't I'm a Dog, written by G. Sherry & W. Walker.
I know it's not "technically correct" English; but since when was rock & roll "technically correct"?

[CBFalconer]

Peter Shaggy Haywood wrote:

.... snip ...
Comments often help me concentrate on what I'm doing. Keep them
simple, short and to the point. Don't try to explain how a whole
500 line function works, in detail, in a single comment,
otherwise you will get distracted. But writing helpful comments
along the way makes coding easier.

If you have a 500 line function the code is almost certainly
already beyond hope. The exception is probably a switch statement.

--
Chuck F (cb********@yahoo.com) (cb********@worldnet.att.net)
Available for consulting/temporary embedded and systems.
<http://cbfalconer.home.att.net> USE worldnet address!

[Flash Gordon]

On Mon, 25 Oct 2004 10:47:42 GMT
CBFalconer <cb********@yahoo.com> wrote:

Peter Shaggy Haywood wrote:

... snip ...

Comments often help me concentrate on what I'm doing. Keep them
simple, short and to the point. Don't try to explain how a whole
500 line function works, in detail, in a single comment,
otherwise you will get distracted. But writing helpful comments
along the way makes coding easier.

If you have a 500 line function the code is almost certainly
already beyond hope. The exception is probably a switch statement.

In general I would say that even if it is a switch statement it is
probably still difficult to read. I would generally write a function for
any case of significant length and call that function.

Of course, every rule has an exception including this one.
--
Flash Gordon
Sometimes I think shooting would be far too good for some people.
Although my email address says spam, it is real and I read it.

[Dan Pop]

In <41***************@yahoo.com> CBFalconer <cb********@yahoo.com> writes:

Peter Shaggy Haywood wrote:

... snip ...

Comments often help me concentrate on what I'm doing. Keep them
simple, short and to the point. Don't try to explain how a whole
500 line function works, in detail, in a single comment,
otherwise you will get distracted. But writing helpful comments
along the way makes coding easier.

If you have a 500 line function the code is almost certainly
already beyond hope. The exception is probably a switch statement.

Well written code seldom needs any comments, if the algorithm used is
known or trivial. If it isn't, the comments should describe the
algorithm, not the code implementing it.

There are exceptions (especially in the presence of micro-optimisation),
but they are exactly this: exceptions.

Most of the comments belong before functions, describing the purpose of
the function, unless it is obvious from the function name and interface.

Dan
--
Dan Pop
DESY Zeuthen, RZ group
Email: Da*****@ifh.de
Currently looking for a job in the European Union

[Eric Sosman]

Joona I Palaste wrote:

Malcolm <ma*****@55bank.freeserve.co.uk> scribbled the following:

"Profetas" <xu*****@yahoo.com> wrote

My theory is that commenting whilst you are coding,
will break your concentration on what you were programming.

If it is something complex.

Does anybody agree?

Yes. Comments are for people, including you after some time, who need to
look at the code after it is finished. If you put in comments during actual
writing you may need to take them out, you may find it hard to "comment out"
code, and, worst of all, you may invalidate a comment and forget to change
it, something no compiler can catch.

One of our source files over at work is rife with comments about some
obscure kludges that had to be inserted and need to be removed in the
future. But over the course of the program's development, no one has
bothered to find out what these kludges exactly are, which part of the
code they affect, and how (or if) they can be removed. So the file still
has comments about "This kludge should be removed by version n" when
we're already in version n+2. Actually the whole file needs complete
replacing but no one has got around to designing a replacement.

Having dealt with many such "permanent temporary
fixes," I found myself wishing for a way to make the
compiler complain -- not now, but at some future date,
so the hack would work for the moment but would draw
attention to itself later on. At first, I thought the
compiler ought to have a construct for such things, but
I eventually changed my mind: The compiler, in and of
itself, is not a complete software engineering tool and
should not be (ab)used as such.

Still, one can often take advantage of assorted
preprocessor symbols that medium-to-large projects often
define. E.g.,

/* This ugly hack works well enough to let the rest
* of the system be tested usefully, but should be
* fixed before we actually release the product.
*/
#ifdef RELEASE
#error "Please fix before shipping"
#else
/* ugly hack goes here */
#endif

Symbols that discriminate "release" from "test" versions
are often useful for this purpose; so, too, are symbols that
specify product versions (you'll ship the hack in version 2.0,
but want to remember to fix it for 2.1). NDEBUG is sometimes
used this way, but "overloading" its meaning is not wonderful.
The main idea is to look for a symbol that will change at some
relevant point in the future, ideally a symbol that is somehow
connected with the need for the hack, and then to plant a time
bomb with a BIG comment explaining what the hack was for and
how to tell whether it can be dispensed with.

--
Er*********@sun.com

[Dan Pop]

In <jq************@brenda.flash-gordon.me.uk> Flash Gordon <sp**@flash-gordon.me.uk> writes:

On Mon, 25 Oct 2004 10:47:42 GMT
CBFalconer <cb********@yahoo.com> wrote:

Peter Shaggy Haywood wrote:

>

... snip ...

>
> Comments often help me concentrate on what I'm doing. Keep them
> simple, short and to the point. Don't try to explain how a whole
> 500 line function works, in detail, in a single comment,
> otherwise you will get distracted. But writing helpful comments
> along the way makes coding easier.

If you have a 500 line function the code is almost certainly
already beyond hope. The exception is probably a switch statement.

In general I would say that even if it is a switch statement it is
probably still difficult to read. I would generally write a function for
any case of significant length and call that function.

This doesn't help when the switch has *many* cases. Such jumbo switches
are not very often, but there are cases when they provide the best
solution to a given problem. Of course, the code handling each case
should not exceed a few lines.

Dan
--
Dan Pop
DESY Zeuthen, RZ group
Email: Da*****@ifh.de
Currently looking for a job in the European Union

[Rob Thorpe]

CBFalconer <cb********@yahoo.com> wrote in message news:<41***************@yahoo.com>...

Peter Shaggy Haywood wrote:

... snip ...

Comments often help me concentrate on what I'm doing. Keep them
simple, short and to the point. Don't try to explain how a whole
500 line function works, in detail, in a single comment,
otherwise you will get distracted. But writing helpful comments
along the way makes coding easier.

If you have a 500 line function the code is almost certainly
already beyond hope. The exception is probably a switch statement.

I would also add: How do you know it's 500 lines long until you've
commented it. A particularly nasty function might require as many
lines of commentary as code, or even twice as many. A 100 line long
function may become ~250 lines long.

You can only assess the complexity of an idea by implementing it *and*
explaining it.

[Alan Balmer]

On Mon, 25 Oct 2004 07:17:17 GMT, ph******@alphalink.com.au.NO.SPAM
(Peter "Shaggy" Haywood) wrote:

Groovy hepcat Profetas was jivin' on Fri, 22 Oct 2004 11:40:15 -0400
in comp.lang.c.
Re: Commenting the source code.'s a cool scene! Dig it!

My theory is that commenting whilst you are coding,
will break your concentration on what you were programming.
If it is something complex.
Does anybody agree?
Someone might, someplace in the World. But I don't.
Comments often help me concentrate on what I'm doing. Keep them
simple, short and to the point. Don't try to explain how a whole 500
line function works, in detail, in a single comment, otherwise you
will get distracted.

But do explain *what* that 500 line function does, in a single
comment.

I am often faced with entire programs which need significant study
just to determine what their purpose is.
But writing helpful comments along the way makes
coding easier.

--
Al Balmer
Balmer Consulting
re************************@att.net

[Ben Pfaff]

Eric Sosman <er*********@sun.com> writes:

Still, one can often take advantage of assorted
preprocessor symbols that medium-to-large projects often
define. E.g.,

/* This ugly hack works well enough to let the rest
* of the system be tested usefully, but should be
* fixed before we actually release the product.
*/
#ifdef RELEASE
#error "Please fix before shipping"
#else
/* ugly hack goes here */
#endif

Wouldn't work at a company I work for, which does continuous
builds of both debug and release versions. People would get
upset that I'd broken the release build. Instead, I'd just file
it in the bug system as needing a fix before release.
--
"I don't have C&V for that handy, but I've got Dan Pop."
--E. Gibbons

[Flash Gordon]

On 25 Oct 2004 14:47:39 GMT
Da*****@cern.ch (Dan Pop) wrote:

In <jq************@brenda.flash-gordon.me.uk> Flash Gordon
<sp**@flash-gordon.me.uk> writes:

On Mon, 25 Oct 2004 10:47:42 GMT
CBFalconer <cb********@yahoo.com> wrote:

Peter Shaggy Haywood wrote:
>
... snip ...
>
> Comments often help me concentrate on what I'm doing. Keep them
> simple, short and to the point. Don't try to explain how a whole
> 500 line function works, in detail, in a single comment,
> otherwise you will get distracted. But writing helpful comments
> along the way makes coding easier.

If you have a 500 line function the code is almost certainly
already beyond hope. The exception is probably a switch statement.
In general I would say that even if it is a switch statement it is
probably still difficult to read. I would generally write a function
for any case of significant length and call that function.

This doesn't help when the switch has *many* cases. Such jumbo
switches are not very often,

Well, since I said "In general" not "Always" that does contradict what I
said.
but there are cases when they provide the
best solution to a given problem. Of course, the code handling each
case should not exceed a few lines.

I've yet to find such a case myself, but I accept that it is possible.
--
Flash Gordon
Sometimes I think shooting would be far too good for some people.
Although my email address says spam, it is real and I read it.

[John Bode]

"Profetas" <xu*****@yahoo.com> wrote in message news:<7f******************************@localhost.t alkaboutprogramming.com>...

Thanks for the reply.

My theory is that commenting whilst you are coding,
will break your concentration on what you were programming.

If it is something complex.
Does anybody agree?

Profetas

Actually, the few times I comment as I go is when I'm working on
something relatively large and complex. Short and simple stuff I can
knock out quickly enough to keep it all in my head, but if I have to
refer back and forth to other files or documentation as I go, I
rapidly lose state.

[Randy Howard]

In article <cl**********@sunnews.cern.ch>, Da*****@cern.ch says...

Well written code seldom needs any comments, if the algorithm used is
known or trivial.
I tend to agree, but I don't think that zero comments is the right
answer. Lightly (but accurately and appropriately) commented code suits
me fine.

Specifically, I don't think that having a comment on or near every line is
of any use at all, as more often than not the comments get out of date
(stale) with respect to their contents under such heavy commenting policies.

On the other hand, some of the most esoteric & bizarre code ever seen (seems
to be an epidemic amongst low level system and driver code) has few or no
comments at all. In one sense, if you can't figure out what that code is
doing, you probably shouldn't be in there. On the other hand, using it as
a test for the next guy, or a barrier to competition isn't a good thing
either.

I tend to write clear block comments at the top of a function describing
the intent, how it works, and why that approach was chosen if there
could be any controversy about that. If a well known algorithm is being
used for something, I give a source for it. I also tend to use longer
"self-commenting" variable names apart from loop variables, and comment
them once at declaration, and let the code speak for itself most other
places unless something is being done that is likely to be misunderstood,
or perhaps accidentally thought to be unnecessary. Examples of the
latter would include platform-specific code, performance optimizations
where the specifics used are critical for some purpose, or other very
complicated code that needs to be there for a non-obvious reason.
If it isn't, the comments should describe the algorithm, not the code
implementing it.

I agree. /* add one to x */ comments and their ilk are a waste of time.

Something like:

/* this code uses XYZ's Algorithm for Random BS extraction per the
* paper at http://randomlink.com/whatever
* At the time this code was implemented it represented the best
* known approach to this problem.
*/

Is the type of thing I do most for anything that might not be obvious
to J. Random Maintenance Programmer.

--
Randy Howard (2reply remove FOOBAR)

[Keith Thompson]

Randy Howard <ra*********@FOOverizonBAR.net> writes:

In article <cl**********@sunnews.cern.ch>, Da*****@cern.ch says...

[...]

If it isn't, the comments should describe the algorithm, not the code
implementing it.

I agree. /* add one to x */ comments and their ilk are a waste of time.

A comment like /* add one to x */ is useful if and only if it's
something the reader doesn't already know. For example, you might
reasonably have

x ++; /* add one to x */

in the first chapter of a C tutorial.

--
Keith Thompson (The_Other_Keith) ks***@mib.org <http://www.ghoti.net/~kst>
San Diego Supercomputer Center <*> <http://users.sdsc.edu/~kst>
We must do something. This is something. Therefore, we must do this.

[Ben Pfaff]

Keith Thompson <ks***@mib.org> writes:

A comment like /* add one to x */ is useful if and only if it's
something the reader doesn't already know. For example, you might
reasonably have

x ++; /* add one to x */

in the first chapter of a C tutorial.

Maybe. But it sets a horrible example in that it implicitly
encourages readers to comment their code the same way.
--
Ben Pfaff
email: bl*@cs.stanford.edu
web: http://benpfaff.org

[Rob Thorpe]

"Profetas" <xu*****@yahoo.com> wrote in message news:<7f******************************@localhost.t alkaboutprogramming.com>...

Thanks for the reply.

My theory is that commenting whilst you are coding,
will break your concentration on what you were programming.

If it is something complex.
Does anybody agree?

Profetas

It doesn't matter when you comment (within reason), so long as you do
it, and you don't let the comments become out of date.

I find the best way to do this is to comment the code as it's written
and the functions at the end, but that's just me.

[Mabden]

"Ben Pfaff" <bl*@cs.stanford.edu> wrote in message
news:87************@benpfaff.org...

Keith Thompson <ks***@mib.org> writes:

A comment like /* add one to x */ is useful if and only if it's
something the reader doesn't already know. For example, you might
reasonably have

x ++; /* add one to x */

in the first chapter of a C tutorial.

Maybe. But it sets a horrible example in that it implicitly
encourages readers to comment their code the same way.

I agree with Ben. The comment should give some explanation of the "why",
not the "what".
The comment should be something more like:

++x; /* move to next screen position */

BTW, ++x reads as "increment x", x++ reads as "do nothing, then
increment x", to me.

--
Mabden

[Mabden]

"Rob Thorpe" <ro***********@antenova.com> wrote in message
news:1a**************************@posting.google.c om...

"Profetas" <xu*****@yahoo.com> wrote in message

news:<7f******************************@localhost.t alkaboutprogramming.com>...

Thanks for the reply.

My theory is that commenting whilst you are coding,
will break your concentration on what you were programming.

If it is something complex.
Does anybody agree?

Profetas

It doesn't matter when you comment (within reason), so long as you do
it, and you don't let the comments become out of date.

I find the best way to do this is to comment the code as it's written
and the functions at the end, but that's just me.

Comments should tell what is going on, without be too intrusive.
Something like this (for my Palm OS game) works for me:

/* Create and label the "Next Tile" box */
RctSetRectangle (&rect, NextTile_Left, NextTile_Top, NextTile_Width,
NextTile_Height);
WinFillRectangle (&rect, 0);
WinPaintRectangleFrame (simpleFrame, &rect);
WinDrawChars ("Next", 4, NextTile_Left+5, NextTile_Top+1);
WinDrawChars ("Tile", 4, NextTile_Left+8, NextTile_Top+Second_Line);

/* Create and label the "Score" box */
RctSetRectangle (&rect, Score_Left, Score_Top, Score_Width,
Score_Height);
WinFillRectangle (&rect, 0);
WinPaintRectangleFrame (simpleFrame, &rect);
WinDrawChars ("Score", 5, Score_Left+5, Score_Top+1);

--
Mabden

[Giorgos Keramidas]

Neil Kurzman <ns*@mail.asb.com> writes:

Profetas wrote:

My theory is that commenting whilst you are coding,
will break your concentration on what you were programming.

If it is something complex.
Does anybody agree?

No one really comments afterward. they just say they will, but there is
never time.

Not to mention that the concentration is already lost in the realm of human
memory, and you might have forgotten already what it all is about.

Seriously now, there are two sorts of `complexity' involved here: algorithmic
complexity and source-level complexity.

The first type of complexity is an inherent property of the algorithms and
data structures used. In this case, extensive documentation of the source
code either in the form of comments or in the form of accompanying (but
external) documents, can help a lot. It also doesn't matter if you write
these sorts of comments when you're actually typing the source, because they
should have already been `written' in some form as part of the overall design.

The second type of complexity, the one that is a side-effect of the language,
the libraries and -- most importantly -- the coding style used, is also
something that comments can help a lot with. In this case, my experience
shows that comments should be written at about the same time as the source
code is typed. It's the best time to do so, because you have all the details
in your mind and you don't need to recall anything from something you did some
time ago.

So, Profetas, IMHO you're partly right... and partly wrong too.

[Giorgos Keramidas]

Da*****@cern.ch (Dan Pop) writes:

In <jq************@brenda.flash-gordon.me.uk>
Flash Gordon <sp**@flash-gordon.me.uk> writes:

On Mon, 25 Oct 2004 10:47:42 GMT
CBFalconer <cb********@yahoo.com> wrote:

Peter Shaggy Haywood wrote:
Comments often help me concentrate on what I'm doing. Keep them
simple, short and to the point. Don't try to explain how a whole
500 line function works, in detail, in a single comment,
otherwise you will get distracted. But writing helpful comments
along the way makes coding easier.

If you have a 500 line function the code is almost certainly
already beyond hope. The exception is probably a switch statement.

In general I would say that even if it is a switch statement it is
probably still difficult to read. I would generally write a function for
any case of significant length and call that function.

This doesn't help when the switch has *many* cases. Such jumbo switches
are not very often, but there are cases when they provide the best
solution to a given problem. Of course, the code handling each case
should not exceed a few lines.

I am also tempted to use lookup tables of handler functions in cases
like this. One expects this to be a bit slower though, as it requires
some overhead for a function call and calling inline functions through
function pointers is, well, not possible ;-)

[Dan Pop]

In <9j************@brenda.flash-gordon.me.uk> Flash Gordon <sp**@flash-gordon.me.uk> writes:

On 25 Oct 2004 14:47:39 GMT
Da*****@cern.ch (Dan Pop) wrote:

This doesn't help when the switch has *many* cases. Such jumbo
switches are not very often,

Well, since I said "In general" not "Always" that does contradict what I
said.

but there are cases when they provide the
best solution to a given problem. Of course, the code handling each
case should not exceed a few lines.

I've yet to find such a case myself, but I accept that it is possible.

Consider the code dealing with opcode mnemonics in an assembler. A jumbo
switch dealing with each mnemonic as a case (by the time you have checked
that it is a valid mnemonic you can also assign it a unique integer value:
its position in the valid mnemonic array) is the most natural approach.

Dan
--
Dan Pop
DESY Zeuthen, RZ group
Email: Da*****@ifh.de
Currently looking for a job in the European Union

[Dan Pop]

In <RW*******************@newssvr21.news.prodigy.co m> "Mabden" <mabden@sbc_global.net> writes:

BTW, ++x reads as "increment x", x++ reads as "do nothing, then
increment x", to me.

You're in dire need of a clue about the semantics of these operators.
They both increment x at an *unspecified* moment, before the next sequence
point, as a side effect, but they yield different values. If their
values are discarded, all semantic differences disappear: the side effect
is identical.

Dan
--
Dan Pop
DESY Zeuthen, RZ group
Email: Da*****@ifh.de
Currently looking for a job in the European Union

[Keith Thompson]

Ben Pfaff <bl*@cs.stanford.edu> writes:

Keith Thompson <ks***@mib.org> writes:

A comment like /* add one to x */ is useful if and only if it's
something the reader doesn't already know. For example, you might
reasonably have

x ++; /* add one to x */

in the first chapter of a C tutorial.

Maybe. But it sets a horrible example in that it implicitly
encourages readers to comment their code the same way.

Good point.

On further thought, the semantics of the ++ operator should probably
be explained in the text, not as a comment in sample source code.
There's no reason a sample program, even in the first chapter of an
elementary tutorial, can't exhibit both good coding and good
commenting.

A comment like /* add one to x */ is useful only as an example of a
bad comment.

--
Keith Thompson (The_Other_Keith) ks***@mib.org <http://www.ghoti.net/~kst>
San Diego Supercomputer Center <*> <http://users.sdsc.edu/~kst>
We must do something. This is something. Therefore, we must do this.

[Mabden]

"Dan Pop" <Da*****@cern.ch> wrote in message
news:cl**********@sunnews.cern.ch...

In <RW*******************@newssvr21.news.prodigy.co m> "Mabden" <mabden@sbc_global.net> writes:

BTW, ++x reads as "increment x", x++ reads as "do nothing, then
increment x", to me.
You're in dire need of a clue about the semantics of these operators.
They both increment x at an *unspecified* moment, before the next

sequence point, as a side effect, but they yield different values. If their
values are discarded, all semantic differences disappear: the side effect is identical.

I know that. I just prefer the first way, as when I am reading the
source it "reads" better, to me. You may prefer the second way, and code
it any way you wish. Some people may prefer "x = x+1;", but I like
"++x;" which I read (in my mind) as increment x. YMMV.

--
Mabden

[Daniel Haude]

On 26 Oct 2004 15:23:39 GMT,
Dan Pop <Da*****@cern.ch> wrote
in Msg. <cl**********@sunnews.cern.ch>

Consider the code dealing with opcode mnemonics in an assembler. A jumbo
switch dealing with each mnemonic as a case (by the time you have checked
that it is a valid mnemonic you can also assign it a unique integer value:
its position in the valid mnemonic array) is the most natural approach.

I like to farm out such code to automatically generated files (by flex or
some hand-written utility).

--Daniel

--
"With me is nothing wrong! And with you?" (from r.a.m.p)

[Dan Pop]

In <sl******************@kir.physnet.uni-hamburg.de> Daniel Haude <ha***@kir.physnet.uni-hamburg.de> writes:

On 26 Oct 2004 15:23:39 GMT,
Dan Pop <Da*****@cern.ch> wrote
in Msg. <cl**********@sunnews.cern.ch>

Consider the code dealing with opcode mnemonics in an assembler. A jumbo
switch dealing with each mnemonic as a case (by the time you have checked
that it is a valid mnemonic you can also assign it a unique integer value:
its position in the valid mnemonic array) is the most natural approach.

I like to farm out such code to automatically generated files (by flex or
some hand-written utility).

Then, you're no longer implementing the thing in C. And I have yet to
see automatic C code generators that produce human-friendly C code.

Dan
--
Dan Pop
DESY Zeuthen, RZ group
Email: Da*****@ifh.de
Currently looking for a job in the European Union

[Daniel Haude]

On 27 Oct 2004 15:01:20 GMT,
Dan Pop <Da*****@cern.ch> wrote
in Msg. <cl**********@sunnews.cern.ch>

I like to farm out such code to automatically generated files (by flex or
some hand-written utility).

Then, you're no longer implementing the thing in C. And I have yet to
see automatic C code generators that produce human-friendly C code.

They don't, but that doesn't matter: What matters is that you can rely on
the ugly, automatically-generated, linked-in spaghetti code being
either consistently correct -- or consistently incorrect (which is usually
quite easily fixable).

What the hell. I don't think we need to argue about the pros and cons of
code generators in here, especially as it is off-topic in this thread.

--
"With me is nothing wrong! And with you?" (from r.a.m.p)

[John Bode]

"Mabden" <mabden@sbc_global.net> wrote in message news:<%%***************@newssvr13.news.prodigy.com >...

"Dan Pop" <Da*****@cern.ch> wrote in message
news:cl**********@sunnews.cern.ch...

In <RW*******************@newssvr21.news.prodigy.co m> "Mabden"

<mabden@sbc_global.net> writes:

BTW, ++x reads as "increment x", x++ reads as "do nothing, then
increment x", to me.

You're in dire need of a clue about the semantics of these operators.
They both increment x at an *unspecified* moment, before the next

sequence

point, as a side effect, but they yield different values. If their
values are discarded, all semantic differences disappear: the side

effect

is identical.

I know that. I just prefer the first way, as when I am reading the
source it "reads" better, to me. You may prefer the second way, and code
it any way you wish. Some people may prefer "x = x+1;", but I like
"++x;" which I read (in my mind) as increment x. YMMV.

Kind of like how declarator syntax causes me to read "int *a;" as "a
is pointer to type int" in my head, even though I know the *correct*
reading is "a is type pointer to int". A subtle difference to some,
maybe, but it's something that continues to irk me, even though it
probably saved me from committing a mistake like

int* a, b;
b = malloc (SIZE * sizeof *b);

that seems to bite a lot of people when they first start using
pointers.

[pete]

Profetas wrote:

Hi,

I know that this is off topic.
I don't think that it is.
Do you comment your source code while coding or after coding.

Either or both.
I try to write code so that no commenting is needed,
but I can't always. CBFalconer once suggested that I should comment
a square root function that I had posted here.
My intention while writing it, was that it should be
that kind of good code that didn't need comments,
but my first attempt to explain it was incorrect,
so I commented it.

--
pete

[Dan Pop]

In <sl******************@kir.physnet.uni-hamburg.de> Daniel Haude <ha***@kir.physnet.uni-hamburg.de> writes:

On 27 Oct 2004 15:01:20 GMT,
Dan Pop <Da*****@cern.ch> wrote
in Msg. <cl**********@sunnews.cern.ch>

I like to farm out such code to automatically generated files (by flex or
some hand-written utility).
Then, you're no longer implementing the thing in C. And I have yet to
see automatic C code generators that produce human-friendly C code.

They don't, but that doesn't matter: What matters is that you can rely on
the ugly, automatically-generated, linked-in spaghetti code being
either consistently correct -- or consistently incorrect (which is usually
quite easily fixable). ^^^^^^^^^^^^^^^^

^^^^^^^^^^^^^^^^^^^

Wishful thinking. When the code is generated by a hand-written
utility you don't even know what went wrong: a bug in the utility or
a bug into the source code processed by the utility. You have to
compare the ugly C code with the source code it came from and try
to figure out what went wrong, which is seldom an easy job: it's
like debugging a C program by examining the assembly output of the
compiler and trying to figure out whether the bug was in the C code
or in the compiler.
What the hell. I don't think we need to argue about the pros and cons of
code generators in here, especially as it is off-topic in this thread.

Guess who introduced them in this thread?

Dan
--
Dan Pop
DESY Zeuthen, RZ group
Email: Da*****@ifh.de
Currently looking for a job in the European Union

[Dan Pop]

In <43**************************@posting.google.com > jo*******@my-deja.com (John Bode) writes:

Kind of like how declarator syntax causes me to read "int *a;" as "a
is pointer to type int" in my head, even though I know the *correct*
reading is "a is type pointer to int".
If you get the semantics right, it doesn't matter how you read it in your
head. I'd call it pointer to int, if I needed to give it a name, which I
don't when reading C code. I conceptualise what it is without giving it
any name.
A subtle difference to some,
maybe, but it's something that continues to irk me, even though it
probably saved me from committing a mistake like

int* a, b;
b = malloc (SIZE * sizeof *b);

that seems to bite a lot of people when they first start using
pointers.

It's the people learning C++ directly that are most prone to this mistake.
K&R2 and the C standard use the only sensible style when declaring
pointers, which is not likely to mislead anyone. That is, until some
foolish newbie discovers the following device:

#define INTPTR int *
INTPTR a, b;

:-)

Dan
--
Dan Pop
DESY Zeuthen, RZ group
Email: Da*****@ifh.de
Currently looking for a job in the European Union