• Advertisement
Sign in to follow this  

Commenting Style

This topic is 4340 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

If you intended to correct an error in the post then please contact us.

Recommended Posts

I'm interested in hearing about how everyone else comments their code. I personally put a comment at the top of each file describing what it is, and if it's a class definition, I describe what the class is used for. Above any functions I place: /* ==================== function name notes ==================== */ I usually only put comments in methods if there is something going on that may not be obvious. I also add little one liners at the end of a class definition or if I have nested control loops, at the end of each larger block. Just curious as to what other people do.

Share this post


Link to post
Share on other sites
Advertisement
The little commenting I do usually consists of a brief // comment right before a chunk of unusual code. I also use TODO: and HACK: prefixes to mark incomplete/bad code. I like to keep the code really compact, concise, and self-documenting whenever possible, sometimes maybe to extremes.

Share this post


Link to post
Share on other sites
Mostly I just use the //. If I need to write a bunch of stuff I'll use the
/*

*/

but that is rare. A lot of the times I don't really comment til after I'm reading back over things and I'll think "I better put something in here about this" and even then it's just the simple // Description

Share this post


Link to post
Share on other sites
Many of my comments are several lines long, explaining the principle behind the code. I used to write a header of comments above the implementation of every function, but as I got more experienced I discovered that most of the funcions were self-explanatory and no comments were necessary. So now I just put a line of //----------... between the implementations, and the comments, if any, go in the header file.

I also use the // TODO: and // HACKHACK: prefixes.

Writing a brief comment above an unusual piece of code goes without saying.

Share this post


Link to post
Share on other sites
I'm with the Doxygen guys. I've been using it for nearly 6 years now. I like it a lot.

Share this post


Link to post
Share on other sites
using /* */ is evil!

a true story:
one day i was getting a crash in the SDL library, so i d'led the source, compiled it and got it working, with the crash still.

So i had to find the bug, which could have been any where, so the only way to isolate the problem was to comment out blocks of code.

now when every line, and every function has a /* */ style comment, and you want to use do do a /* */ to comment out slabs of code, your life becomes hell! it took me many hours to remove thier comments.

Eventually found the problem and vouewd only to use /* */ for commenting out blocks temporary!

Share this post


Link to post
Share on other sites
Quote:

using /* */ is evil!

Eventually found the problem and vouewd only to use /* */ for commenting out blocks temporary!


#if 0
I am commented out!
/* ... */
So am I!
#endif

Share this post


Link to post
Share on other sites
Quote:
Original post by Mace
Once you go XML youll never go back ;)


So it's like Christopher Reeves being stuck in a wheelchair never going back to being Superman??? :)

Share this post


Link to post
Share on other sites
For functions, I do this:


//************************************************************************
//** Function: [function name goes here]
//** Job: [a quick description of what the function is used for goes here]
//************************************************************************
BOOL Func()
{
//...
return TRUE;
}

Share this post


Link to post
Share on other sites
Quote:
Original post by Troll
Quote:
Original post by Mace
Once you go XML youll never go back ;)


So it's like Christopher Reeves being stuck in a wheelchair never going back to being Superman??? :)


lol!

I use very long separators. Apt for big resolutions. Not recommended for line wraping.

/*========================================================================================================================================================================================================================================================================================================================================================================================================*/


Share this post


Link to post
Share on other sites
Quote:
Original post by supagu
using /* */ is evil!


1° That's a flaw in C and C++ for not supporting nested comments.
2° Syntax highlighting would point out that a comment block is incomplete.
3° "Comment-out" macros in most IDEs and editors use "//" in C++.
4° As was mentioned, #if 0 is also useful

Also, note the almighty /*"/**/ construct, which has the nice property of being an all-ender: it stops both open string literals and comments, as such:

/* This is a comment /*"/**/
"This is an unfinished literal/*"/**/

Myself, I use Doxygen, XML, javadoc or ocamldoc depending on the language.

Share this post


Link to post
Share on other sites
Quote:
Original post by ToohrVyk
Myself, I use Doxygen, XML, javadoc or ocamldoc depending on the language.


Could you tell me how Doxygen helps with commenting? I went to the web site, but I still don't understand how it helps you. I was hoping to see a screen shot or something.

Share this post


Link to post
Share on other sites
Quote:
Original post by caseyd
Above any functions I place:

/*
====================
function name
notes
====================
*/

This really annoys me - whats the point of putting functionName in the comment when all you've done is duplicate the actual name just after the comment? It doesn't add anything except extra visual noise.

The only thing I find it good for is when it doesn't match the actual function itself. This tends to set off big alarms in my head as usually it means someones done a quick copy-paste job and I'm about to read some badly thought out hacky code. [rolleyes]

Share this post


Link to post
Share on other sites
Quote:
Original post by OrangyTang
Quote:
Original post by caseyd
Above any functions I place:

/*
====================
function name
notes
====================
*/

This really annoys me - whats the point of putting functionName in the comment when all you've done is duplicate the actual name just after the comment? It doesn't add anything except extra visual noise.
[rolleyes]


what if you had a function like this:


const std::vector<Sometype>& MyPrettyClass::MyPrettyMethod(Sometype* MyPrettyParameter)





/*=:: MyPrettyClass :: ==============================================================================================================================================================
/*
/* MyPrettyMethod
/*
/*===============================================================================================================================================================*/


const std::vector<Sometype>& MyPrettyClass::MyPrettyMethod(Sometype* MyPrettyParameter)


Share this post


Link to post
Share on other sites
Quote:
Original post by owl
Quote:
Original post by OrangyTang
Quote:
Original post by caseyd
Above any functions I place:

/*
====================
function name
notes
====================
*/

This really annoys me - whats the point of putting functionName in the comment when all you've done is duplicate the actual name just after the comment? It doesn't add anything except extra visual noise.
[rolleyes]


what if you had a function like this:

What about it (other than proving that C++ has a somewhat verbose and ugly syntax)? If you want to improve it then a typedef for the return type would help a good amount. If you're still not satisfied then I'd suggest a better syntax highlighter than this forum's. Changing the colour of all brackets can help considerably.

Share this post


Link to post
Share on other sites
Quote:
Original post by OrangyTang
Quote:
Original post by caseyd
Above any functions I place:

/*
====================
function name
notes
====================
*/

This really annoys me - whats the point of putting functionName in the comment when all you've done is duplicate the actual name just after the comment? It doesn't add anything except extra visual noise.


I think the point is so that when you are scrolling your code, you can see which function you're looking at and what its purpose is without ever having to look at the actual code (comments only). Also, it confirms which function you're talking about. Though most people would put such a comment above a function, they could put it below. I guess it's a matter of personal preference.

Share this post


Link to post
Share on other sites
Quote:
Original post by OrangyTang
Quote:
Original post by owl
Quote:
Original post by OrangyTang
Quote:
Original post by caseyd
Above any functions I place:

/*
====================
function name
notes
====================
*/

This really annoys me - whats the point of putting functionName in the comment when all you've done is duplicate the actual name just after the comment? It doesn't add anything except extra visual noise.
[rolleyes]


what if you had a function like this:

What about it (other than proving that C++ has a somewhat verbose and ugly syntax)? If you want to improve it then a typedef for the return type would help a good amount. If you're still not satisfied then I'd suggest a better syntax highlighter than this forum's. Changing the colour of all brackets can help considerably.


Yeah. It happens that you may want to make a brief resume of what the function is all about. The comment may be not so brief sometimes, and it's nice to see the function name heading it.

But it's a matter of personal preference.

Share this post


Link to post
Share on other sites
Quote:
Original post by supagu
using /* */ is evil!

a true story:
one day i was getting a crash in the SDL library, so i d'led the source, compiled it and got it working, with the crash still.

So i had to find the bug, which could have been any where, so the only way to isolate the problem was to comment out blocks of code.

now when every line, and every function has a /* */ style comment, and you want to use do do a /* */ to comment out slabs of code, your life becomes hell! it took me many hours to remove thier comments.

Eventually found the problem and vouewd only to use /* */ for commenting out blocks temporary!


Same here. And what I do quite often with code blocks that need to be commented in/out often:

/*
code...
//*/

By doing so I don't need to add/remove the closing */ at the end. That is particularly useful when the code block to be commented out is long.

Share this post


Link to post
Share on other sites
Quote:
Original post by Konfusius
I use doxygen, but Natural Docs looks sweet, too.

Has anyone used this yet? This looks fantastic!

Share this post


Link to post
Share on other sites
Sign in to follow this  

  • Advertisement