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.hel sinki.fi) ------------- Finland --------\
\-------------------------------------------------------- rules! --------/
"Hasta la Vista, Abie!"
- Bart Simpson

[dandelion]

"Profetas" <xu*****@yahoo. com> wrote in message
news:ca******** *************** *******@localho st.talkaboutpro gramming.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******* *************** ********@localh ost.talkaboutpr ogramming.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******* *************** ********@localh ost.talkaboutpr ogramming.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).