Hi Xbliters,

Anybody that produces code has an opinion on what is a good comment. I
would like to start a thread of discution on this topic for a long
time.

If you read my article "An Xblite Primer", posted in the Google Group as
http://groups.google.fr/group/xblite/web/xblite002, in paragraph
"V. Learning to learn", I wrote:
(...) There is a point to make about code commenting. Comments are
invaluable to document your findings. I intend to write a short
article on code commenting and I would appreciate any kind of input on
this topic. (...)

My intention is to propose such an article for the next issue of
PCOPY! I am not planning to make it a long one but, if this discution
stirs a lot of ideas, this can produce a bigger and better "white
paper".

To prime the discution, let me remind you that a program can be
commented at many levels:
- to clarify the code (yes, I put it first!)
- to identify the Author(s)
- to indicate the copyright
- to remind of the pending to-dos
- to document the algorithms in use
- to ease the code review in an Open-Source context or a cooperative
  development
- to leave a maintenance trail
- to layout the coding convensions
- to make a professional impression
- to warn for missing features, known bugs etc.
- ...

And it's just for a starter! So, what can you say?

Welcoming any comment :-)
Guy