Commenting/Documenting

K

Kan D.

Hey there everyone

Question

What is the best way to use comment/document in plain english what we do
within the modules

Should the top of each module read something like this? ---

'Developed by: so and so
'Date: month, year
'Summary: brief explanation of object


And then the first line in each Sub should read something like this? ---

'Summary: brief explanation of procedure/function



And, of course, leaving the comments above lines that are difficult to
grasp, as an aid to the developer as well as the person trying to decipher
it (at a later date, this to roles may/may not involve the same person)


Sound like the right way to use comments?

Please suggest

Kan
 
D

Douglas J. Steele

Sounds good.

You might also want to include a section to indicate what changes were made
over time.
 
K

Kan D.

Douglas,

Noticing that you respond to a lot of posts from different people/different
backgrouns...

Do you find commenting to be a challenge for most, and perhaps yourself?

It's hard for me to explain the work I've done to a developer who has a
different approach, know-what-I-mean?
 
K

Kan D.

Another thing

How do you explain the laws of physics and Einstein philosophy to a
kindergartener

And for that matter, how I explain to myself what I've done

Commenting is monotonous, because I just find myself explaining what the
overall purpose of the sub is. But I don't feel like I'm actually
connecting with myself on a laimans terms basis, let alone other people.
 
D

Douglas J. Steele

Having to adapt to different people's styles (or lack of style) is part of
the fun! <g>

I see it as mental calisthenics: makes sure I'm not stuck at looking at
problems in one way only.
 
S

Stefan Hoffmann

hi,
Having to adapt to different people's styles (or lack of style) is part of
the fun! <g>

I see it as mental calisthenics: makes sure I'm not stuck at looking at
problems in one way only.
Click to expand...


See http://www.canonical.org/~kragen/tao-of-programming.html :

--
A novice asked the Master: ``Here is a programmer that never designs,
documents or tests his programs. Yet all who know him consider him one
of the best programmers in the world. Why is this?''

The Master replies: ``That programmer has mastered the Tao. He has gone
beyond the need for design; he does not become angry when the system
crashes, but accepts the universe without concern. He has gone beyond
the need for documentation; he no longer cares if anyone else sees his
code. He has gone beyond the need for testing; each of his programs are
perfect within themselves, serene and elegant, their purpose
self-evident. Truly, he has entered the mystery of Tao.''
 
K

Kan D.

what the heck is Tao?

Stefan Hoffmann said:
hi,



See http://www.canonical.org/~kragen/tao-of-programming.html :

--
A novice asked the Master: ``Here is a programmer that never designs,
documents or tests his programs. Yet all who know him consider him one of
the best programmers in the world. Why is this?''

The Master replies: ``That programmer has mastered the Tao. He has gone
beyond the need for design; he does not become angry when the system
crashes, but accepts the universe without concern. He has gone beyond the
need for documentation; he no longer cares if anyone else sees his code.
He has gone beyond the need for testing; each of his programs are perfect
within themselves, serene and elegant, their purpose self-evident. Truly,
he has entered the mystery of Tao.''
Click to expand...
 
Top