Jump to content
  • Advertisement
Sign in to follow this  

commenting style

This topic is 4317 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

Quick simple newb question on commenting style, is it standard to put method header documentation comments in the header files, source files, or both? Thanks, -sevans

Share this post


Link to post
Share on other sites
Advertisement
I usually do most of my documenting in the header file and then I just break up new functions with something like this:
//===========================================
//Function functionName
//===========================================

This makes it easier for me find functions in my implementation file. I do document items that are hard to understand no matter where they are but IMO useless comments can be as bad as no comments. I use to be bad about writing obvious stuff like this.

//Function used to find a path to a goal Node
bool FindPath(Node& goal);

Looking at this now, the comment is useless what would be better is explaining how not what it does. I should comment something about what algorithm is used and that it returns false until a path is found.

Share this post


Link to post
Share on other sites
Unless your method header comments are in a metaformat used to generate documentation (via ndoc, doxygen, javadoc and similar tools), they're useless. You can more quickly locate methods by navigating your class space with a quality IDE.

You do use a quality IDE, right? Right?

Share this post


Link to post
Share on other sites
Quote:
Original post by Oluseyi
Unless your method header comments are in a metaformat used to generate documentation (via ndoc, doxygen, javadoc and similar tools), they're useless. You can more quickly locate methods by navigating your class space with a quality IDE.

You do use a quality IDE, right? Right?


I use Visual Studio .Net 2003 Professional and Visual Studio .Net 2005 Standard Edition. I think you may have mentioned something I didn't know about what do you mean by navigating your class space?

Share this post


Link to post
Share on other sites
You bough Visual Studio Standard Edition for $300, and you don't know how to navigate the class space?

Just click "View -> Class View" and you will be able to browse classes, namespaces, functions, whatever and jump to the definition.

Share this post


Link to post
Share on other sites
Well, you do use a quality IDE.

First, let me reccomend Visual Assist X

Second, take a look at the dropdown boxes at the top of your code window... Also, you can type in the class name press . and it'll basically list everything in there. Or just right click on the function name and go to the definition...

It's very easy to navigate your classes in visual studio... And again, even easier with Visual Assist X.

Edit (beaten to the punch) and Simian Man: I got it for free through my university's MSDNA program. Hell, I get almost all Microsoft products for free, just not Office. He could easily have gotten it that way.

and my commenting style is as follows:


Block quotes
/*----------------------------*\
| Class: Name |
| details which may span lines |
| Creator Info: |
| Date: |
\*----------------------------*/


anything else:

//Whoa, holy crap it's just a comment.






And I put interface usage comments in my header files.

I put very few comments in my .cpp files, nobody should be mucking with them anyway, and if you are, you'd better know how to read code. I comment my shit if it's really obtuse or if it's a hacky nasty implementation. I put /*WOG*/ wherever stuff needs to be added so that I can just do a search for WOG and find unimplemented features... Yes, I'm odd.

Share this post


Link to post
Share on other sites
Quote:
Original post by Simian Man
You bough Visual Studio Standard Edition for $300, and you don't know how to navigate the class space?

Just click "View -> Class View" and you will be able to browse classes, namespaces, functions, whatever and jump to the definition.


Yeah pretty sad huh, I am so use to just having the solution explorer open or the properties explorer. Thanks that will definately be a handy tool to use :)

Just a quick note, I did get VS 2005 .Net for free through my university, otherwise I would have just kept 2003. I really have a lot of computer lockup problems with 2005 lately, im not sure why. Especially if the programs get rather large. So I have been doing a lot of my programming in VS 2003. I have a pretty good computer too so I don't know what would cause the lockups. It usually happens when I go to debug or when I am going to click something in the menu. I will probably reinstall it to see if that fixes anything.

Share this post


Link to post
Share on other sites
@Oluseyi so for document generating software like doxygen, do you place you documentation in the header or source files?

@M2tM yeah thats how I got my VS03 and VS05 :)

And I use Code::Blocks when I am doing simple c++ console apps like this one. For windows apps and D3D I use VS05.

-sevans

Share this post


Link to post
Share on other sites
Quote:
Original post by Sevans
@Oluseyi so for document generating software like doxygen, do you place you documentation in the header or source files?

Source, because that's where the implementation lies. And the implementation may change, and the documentation should reflect that.

I actually hate header files because they duplicate maintenance. If C++ had at least a two-pass compilation model, I'd be able to get rid of them once and for all. Fortunately, Visual Studio will gladly maintain header files for you when you change function signatures.

Share this post


Link to post
Share on other sites

/*----------------------------*\
| Class: Name |
| details which may span lines |
| Creator Info: |
| Date: |
\*----------------------------*/

I've never understood this sort of commenting. How on earth do you manage the alignment of the right hand side without tearing your hair out every time you make changes? Why force people who maintain your code to do the same or rewrite all the comments?

Share this post


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

  • Advertisement
×

Important Information

By using GameDev.net, you agree to our community Guidelines, Terms of Use, and Privacy Policy.

Participate in the game development conversation and more when you create an account on GameDev.net!

Sign me up!