source code commenting

[lallous]

Hello

I've been programming for a number of years, however my commenting style is
always different.
Sometimes I use something like:

/************************
* method ....
* comments...
*************************/

Sometimes I use:
//
// this function is for this and that...
// ...

etc...then when it comes to write documents about my code, I'ld have to
rewrite lots of explanation about the code in another document.

I don't know what style to adopt and what tools can later parse my code and
generate documentation out of my specially formatted comments. (for example
Javadoc, can parse source-code and generate comments)

What do you use?
What do you suggest?

Regards,
Elias

 

[Rolf Magnus]

Hello

I've been programming for a number of years, however my commenting style
is always different.
Sometimes I use something like:

/************************
* method ....
* comments...
*************************/

Sometimes I use:
//
// this function is for this and that...
// ...

etc...then when it comes to write documents about my code, I'ld have to
rewrite lots of explanation about the code in another document.

I don't know what style to adopt and what tools can later parse my code
and generate documentation out of my specially formatted comments. (for
example Javadoc, can parse source-code and generate comments)

Yes, you should format those comments in such a way that they can be used by
a documentation too.

What do you use?
doxygen

What do you suggest?

doxygen

See http://www.doxygen.org

 

[Ben Pope]

Yes, you should format those comments in such a way that they can be used by
a documentation too.


doxygen

See http://www.doxygen.org

ditto (with the Javadoc style comments, 'cos I learnt with Java)

Ben Pope

 

[Ben Radford]

Hello

I've been programming for a number of years, however my commenting style is
always different.
Sometimes I use something like:

/************************
* method ....
* comments...
*************************/

Sometimes I use:
//
// this function is for this and that...
// ...

etc...then when it comes to write documents about my code, I'ld have to
rewrite lots of explanation about the code in another document.

I don't know what style to adopt and what tools can later parse my code and
generate documentation out of my specially formatted comments. (for example
Javadoc, can parse source-code and generate comments)

What do you use?
What do you suggest?

Regards,
Elias

I use doxygen to generate documentation and after changing style many
times I have settled on // C++ style commenting. This way I can use C
style comments to disable entire sections of code during debugging and
not have to worry about whether the compiler will have a fit because of
nested comments.

 

[roberts.noah]

I use doxygen to generate documentation and after changing style many
times I have settled on // C++ style commenting. This way I can use C
style comments to disable entire sections of code during debugging and
not have to worry about whether the compiler will have a fit because of
nested comments.

I just use the preprocessor when I am worried about that. Of course
I'm not the only one developing and I'm comming in on a 10 year old or
more product....I don't get to establish style guidelines and stick to
them...they are given to me and with the age and the amount of hands
that have been in the pot wel....not everyone follows style guidelines.

#if 0

CODE

#endif

will block out anything no matter what comments, etc, are in CODE. The
only time you run into trouble is if you split another preprocessor
segment and it splits your new one as well.

 

[Ben Radford]

#if 0

CODE

#endif

I hadn't thought of that but it works just as well as my method. I use
mine because my editor will highlight the comments in grey and italics
making it easy to see what has been disabled. Just a minor point though.

 

[Marcus Kwok]

I hadn't thought of that but it works just as well as my method. I use
mine because my editor will highlight the comments in grey and italics
making it easy to see what has been disabled. Just a minor point though.

My editor will also highlight the #if 0 ... #endif block the same as
comments. However, I don't wish to start an editor war so that's all
I'll say about this.

 

[Ben Radford]

My editor will also highlight the #if 0 ... #endif block the same as
comments. However, I don't wish to start an editor war so that's all
I'll say about this.

Hehe =). I don't view my editor religiously so there's no danger of that
happening; especially as I've just discovered it *does* infact highlight
#if 0 ... #endif blocks. I should probably have checked this before I
posted it as the reason for my preference.

 

[Jim Langston]

Hello

I've been programming for a number of years, however my commenting style
is always different.
Sometimes I use something like:

/************************
* method ....
* comments...
*************************/

Sometimes I use:
//
// this function is for this and that...
// ...

etc...then when it comes to write documents about my code, I'ld have to
rewrite lots of explanation about the code in another document.

I don't know what style to adopt and what tools can later parse my code
and generate documentation out of my specially formatted comments. (for
example Javadoc, can parse source-code and generate comments)

What do you use?
What do you suggest?

Regards,
Elias

Personally, I only use // for comments. I use /* */ to comment out blocks
of code only.

Too much of a pain to search for /* to find commented out code and running
into comments.

Although I will use // to comment out a single line of code.