Back to General and Gameplay Programming

Fancy C++ comments.

General and Gameplay Programming Programming

Started by JackOfAllTrades December 03, 2010 08:48 PM

29 comments, last by mind_wipe 13 years, 4 months ago

JackOfAllTrades

109

Author

December 03, 2010 08:48 PM

In my library I added very in depth comments to every single class, function, and variable in the headers. The comments are similar to MSDN code reference. For example:

	// ===============================================================================	// Parameters:	//	// mesh	//     [in] The mesh object that will be displayed for the actor.	//	// radius	//     [in] The radius of the actor's capsule within the physics scene which is the distance at which a	//     character comes in contact with objects in the character's vertical plane.	//	// height	//     [in] The hieght of the actor's capsule within the physics scene which is the distance at which a	//     character comes in contact with objects in the character's horizontal plane.	//	// matrix	//     [in] The matrix which defines the the starting pose of the actor.	//	// Return Value:	//     Returns a pointer to the actor. 	//	// Remarks:	//     This function adds a actor to the scene. Actors use a character controller class within the physics	//     scene that offers a standard video game character interface.	// ===============================================================================	AxActor* CreateActor( AxMesh* mesh, float radius, float height, XMMATRIX* matirx );

When in Visual C++ you can see these comments in a popup box as you are browsing the variables and functions of a class. To me this is a pretty awesome way to use comments as an in source reference manual.

I notice that DirectX and many other professional APIs don't do this and this makes me wonder if it's a good idea. Is it a good or bad thing that I am doing this and why?

Want an easy to use open source 3D video game SDK that handles Physics, Graphics, Audio, and AI right out of the box?

zerothrillz

152

December 03, 2010 09:00 PM

Yea, it's pretty clean looking. I don't think anyone can tell you that it's good or bad. All that matters is that it helps you understand your code.

Just don't get all stuck spending massive time writing comments that no ones going to read ever.

smasherprog

570

December 03, 2010 09:01 PM

Are you wondering why there are not large sections of comments like this in directx? Large code comments like what you posted are fine for small projects, but when the amount of actual code becomes large, those comments make readability extremely difficult.

Wisdom is knowing when to shut up, so try it.
--Game Development http://nolimitsdesigns.com: Reliable UDP library, Threading library, Math Library, UI Library. Take a look, its all free.

SeaBourne

120

December 03, 2010 10:06 PM

I rather suggest using the ones in doxygen rather than those comment styles as they are more work to create and make the code header more verbose than needed.

KulSeran

3,272

December 03, 2010 11:09 PM

Quote:Original post by smasherprog
Are you wondering why there are not large sections of comments like this in directx? Large code comments like what you posted are fine for small projects, but when the amount of actual code becomes large, those comments make readability extremely difficult.

This.
If you have a 100% fixed interface on your shipped library. Then by all means, document in the code if you want. If you are working on an inproduction game, enjoy trying to maintain it.

In a header, while it may seem useful, it quickly makes the file hard to grok quickly, as it spaces out the code too much. (sure folding, intelesense, and whatnot help fix this but they aren't always available). A header file is your way to view an interface for something, and should be 100% as useful with out without your standard tools.

Secondly, code is mutable. While radius and height may be all your CreateActor needs now, maybe later on you will need to pass a "width" and a "color" and then you may consolidate it into a "struct ActorParams". Keeping all that documentation in sync on a fast changing code base is a nightmare. Prefer to have code that is self commenting. Infact, your sample is more readable without the comments. If you comment, you should be outlining purpose and gotchas, not the nitty gritty that is obvious.

Try this:

// CreateActor,// Returns a new actor, or NULL if out of reserves. displayMesh may be NULL.AxActor *CreateActor( AxMesh *displayMesh, float collisionRadius, float collisionHeight, XMMATRIX *spawnLocation );

My Blog

Decrius

100

December 04, 2010 02:07 AM

I'd say, avoid _documenting_ your code _inline_ (but do it properly external!), and only start commenting your code in the rare cases it is needed. For the reasons KulSeran gave.

[size="2"]SignatureShuffle: [size="2"]Random signature images on fora

szecs

2,990

December 04, 2010 02:17 AM

When I was learning openGL I just took a look on the header file and I knew (most of the times) what a function did. I would use more descriptive names, so the thing becomes self explaining.

Maybe it's just me, but I usually group parameters so that similar types/looking parameters are grouped. But always: output parameters first, input parameters last. But it's just personal preference.

So:

AxActor* CreateActor( AxMesh* display_mesh, XMMATRIX* pose_matirx, float physics_radius, float physics_height); // or maybe: float collision_radius, float collision_height

Okay, I've just woken up and the names are a bit clumsy, but I guess you get the idea:

description of the parameters: parameter names themselves
remarks: the function name itself
return value: it should be obvious by the return type, or the function name and return type

EDITED a bit

[Edited by - szecs on December 4, 2010 2:17:24 AM]

[size=2]Portfolio [size=2]| Youtube channel | Paper modeller development blog | Journal

Zipster

2,420

December 04, 2010 02:25 AM

Most of the comments I see on a daily basis are either incorrect, outdated, help very little because they lack any context or explanation and are more like quick "notes" for the original implementer, or don't provide any helpful information because they explain the obvious:

// Clearing the string, just in case you were't familiar with the standard library and shouldn't be working here in the first place
myStr.clear();

As such, I've tried to cut down on comments unless something is legitimately going to be difficult to understand, in which case I write a few sentences. Systems and architectures in general are documented in a separate Wiki.

ApochPiQ

23,138

December 04, 2010 03:26 AM

Never repeat yourself.

This especially means that you shouldn't be commenting information that can be obviously inferred from the code itself. By corollary, it means you should be choosing your code structure and namings carefully in order to maximize the amount of information conveyed via the code itself and totally eliminate the need for verbose external comments.

Wielder of the Sacred Wands
[Work - ArenaNet] [Epoch Language] [Scribblings]

flodihn

292

December 04, 2010 04:04 AM

Quote:Original post by Zipster
Most of the comments I see on a daily basis are either incorrect, outdated, help very little because they lack any context or explanation and are more like quick "notes" for the original implementer, or don't provide any helpful information because they explain the obvious:

// Clearing the string, just in case you were't familiar with the standard library and shouldn't be working here in the first place
myStr.clear();

As such, I've tried to cut down on comments unless something is legitimately going to be difficult to understand, in which case I write a few sentences. Systems and architectures in general are documented in a separate Wiki.

Yes self explanatory comments like that is useless, it is much better to comment trickier part of the code.
Also having a description of each function, what it does and returns helps a lot for maintainability.

For example when I write code, almost 2/3 of the lines are function/class/module descriptions used to generate the API. Often my code is pretty simple so I do not put many comments in the code itself. However there are parts that has at least a few lines of comments in trickier parts of the function.

For example this would be a good comment:

if(vertexCount <= 0) {     // Easy memory leak here if we forget to delete mFaces before returning.    delete[] mFaces;    return;}

And this would be a bad comment:

if(vertexCount <= 0) {     // Freeing up faces.    delete[] mFaces;    return;}

For C/C++/PHP I used doxygen successfully, with Erlang edoc is the way to go.

https://www.abydosentertainment.com

Fancy C++ comments.

This topic is closed to new replies.

Popular Topics

Recommended Tutorials

Fancy C++ comments.

This topic is closed to new replies.

Popular Topics

Recommended Tutorials

Reticulating splines