Jump to content
  • Advertisement

Archived

This topic is now archived and is closed to further replies.

OctDev

Your Commenting Style

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

For those of you who tend to comment fairly well: Do you typically include file, class, and function comment headers in both your header and source files, just your header files, or just your source files? For my current project I am trying to be a little more specific about my coding style. I am leaning towards all of my major comment headers in my header files. I figure these are what I will reference down the road when interfacing with files/classes/functions, so the commenting should be there. Additionally, I figure this keeps huge comment blocks out of my way when actually writing the source. What''s your preference? Hmmm, another thought. Do you use comment documentaters (like javadoc)? I don''t really plan to, and have my own preference for how I am going to comment. I don''t really plan for this code to be released, but maybe for my own futur benefit I should structure my comments to be compatible with a documenter. Your thoughts? The Tyr project is here.

Share this post


Link to post
Share on other sites
Advertisement
My file/function/class comments are only in header files. It''s best to always keep things in one place, so changing the other place won''t break consistensy. And I comment in Doxygen/Javadoc style:

/// Class description.
class Foo {
public:
/// Function description.
/// @return width of the universum
int bar();
};

And I tend to leave out comments if they''re self evident from the function name and context.

Share this post


Link to post
Share on other sites
I include most of my procedural comments in the code itself. Object/structure documentation is in the header files, since that is where they are defined. I take this approach mostly for personal convenience-- I tried commenting header file prototypes but they became very ugly and hard to manage pretty quickly. And since I''m using Visual Studio exclusively for development, use of the F12 hotket when the cursor is overtop a keyword will take me instantly to the code for that function anyways. From there I can examine both the commenting and, if need be, the code itself to make sure I''m using it properly.

I do most of my coding for myself only though. I''ve found that when working with others, they tend to expect to find a little more information in the header files. Personally, I never thought to look in header files for commenting to start with. After all, none of the ANSI C or Windows headers have much in the way of comments... in fact they comment procedures on the code-side of things as well if you take a look at the CRT lib sources provided with Visual Studio 6.

- Air

Share this post


Link to post
Share on other sites
There are two main purposes to documentation comments:

1) To tell people about classes and functions so they will know how to use them.

2) To describe what is taking place in the implementation of the function.

To do 1) it makes sense to put it in the header.
Often 2) is unnecessary. Using meaningful names, replacing ints with enumerations, or replacing enumerations with classes etc. can help express the design and intent of code without needing comments. Refactoring suggests that comments can be a bad smell . If you need to comment it possibly means you could remove the code and put it in a seperate function with a meaningful name. Short functions are less likely to need commenting as you don't need to give a narration like 'now that we've finished sorting we add the ... to the ...' etc. You'll just have a sequence of functions with meaningful names which provide their own documentation.
Comments for a function like
bool Rotator(int distance, int direction, int x, int y) are a necessary pain as it's difficult to remember which int means what. But if those values were put into a meaningful class or enumeration the function would become far more obvious in its intent:

    
enum HitOrMiss{Hit, Miss};
Axis::Axis(Vector3 direction) {
...
Rotation::Rotation(Angle theta, Axis spindle) {
...
HitOrMiss Rotator(Rotation rot) {
//etc.


This is all just suggestions that I have found meaningful and useful. This topic is one of those that often turns into a religious war.

Peace.

edit: I just dug up this link

[edited by - petewood on March 24, 2003 6:36:59 AM]

Share this post


Link to post
Share on other sites
Well at some point I do plan on showing this code base to prospective employers. I tend to use descriptive variables, and try and make the code as self-documenting as possible, but I think that for a propective employer it would be best to comment all of the primary components and to do it in a standard manner as well.

My only concern with not commenting "To describe what is taking place in the implementation of the function" deals with code that you don''t plan to maintain or that a team member may heavily modify, espeically in the eyes of employers . I do agree that this has the potential to become a crusade; so far I have received some good responses taht are helping me to solidify and justify my own style, so thanx!

Share this post


Link to post
Share on other sites
We do javadoc style comments in headers as well, describing the classes and functions and how to use them.

The implementation files it doesn''t really matter. The comments in there are to clearly separate the end of one method from the beginning of the next (at a glance) and to describe what''s going on when it''s not self evident by the code (describing reasoning or expected outcomes of certain parts of the code). There''s no line by line commenting.

Share this post


Link to post
Share on other sites
Ed''s Style

I almost always do what you said. I comment in a large block, then I comment the end of a function. If I believe my code needs some more comments to be better, than I''ll add them, but I restrict myself to 1 line.

Share this post


Link to post
Share on other sites
just want to mention that if you add a comment behind the definition of a class member it will show up in mvc++ when you pick this function from the popdown list

Share this post


Link to post
Share on other sites
Guest Anonymous Poster
http://www.perlmonks.org/index.pl?node_id=64709
http://www.perlmonks.org/index.pl?node_id=52497

Share this post


Link to post
Share on other sites
Guest Anonymous Poster
In general i would say i favor the style described as public documentation, minimal commenting. I would draw a line between ''documentation'' and ''commenting''. Documentation is a piece of text that says "you call loadFile(char*) to load a file". Commenting is "int ox=x-(int)(x/64) //find the remainder". That said, if you need to comment the majority of your code, you are doing something wrong. Your comments should be short, and only useful for situations where it isn''t immediately obvious, if for no other reason then that your comments will fall quickly out of synch with the code,leading to worse reading then no comments at all.

Share this post


Link to post
Share on other sites

  • 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!