Jump to content
  • Advertisement
Sign in to follow this  
SteveDeFacto

Fancy C++ comments.

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

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?

Share this post


Link to post
Share on other sites
Advertisement
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.

Share this post


Link to post
Share on other sites
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.

Share this post


Link to post
Share on other sites
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.

Share this post


Link to post
Share on other sites
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 );

Share this post


Link to post
Share on other sites
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.

Share this post


Link to post
Share on other sites
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]

Share this post


Link to post
Share on other sites
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.

Share this post


Link to post
Share on other sites
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.

Share this post


Link to post
Share on other sites
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.

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.

We are the game development community.

Whether you are an indie, hobbyist, AAA developer, or just trying to learn, GameDev.net is the place for you to learn, share, and connect with the games industry. Learn more About Us or sign up!

Sign me up!