Archived

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

Your Commenting Style

This topic is 5383 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
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
I comment a lot, but mainly because I''m a beginner and I don''t want to forget why I coded something in six months time

I have descriptive class and function headers, but my file headers tend to be short and sweet. Also, I plan a lot of my functions in pseudo code first, then as I fill them out the pseudo code becomes the comments.




pan narrans | My Website | Study + Hard Work + Loud Profanity = Good Code

Share this post


Link to post
Share on other sites
I don''t comment my code at all (well, once in a rare while I will, but usually comments are code that is temporarily removed).

So far, I''ve only had a single problem understanding my code and that was after almost a year away from it. If I had spent more time on the code, I could have made it more clear, but I wanted to get it done fast at the time so I threw in some hacks to add functionality. Now I don''t feel like rewriting it so I just spent about an hour figuring it out and adding a couple of lines of comments.

I agree with whoever said that if you need a lot of comments you are coding incorrectly. Class names, function names, and variable names should be descriptive enough to give the gist of what the code is doing. If you are using strange algorithms that aren''t easily understood, it would probably be better to include a reference to a document describing the algorithm.

Share this post


Link to post
Share on other sites
quote:
Original post by Extrarius
...if you need a lot of comments you are coding incorrectly...

Surely there is a difference between relying on comments, and including them for the purposes of clarity (as a beginner, for potential employers, and for colleagues)?


pan narrans | My Website | Study + Hard Work + Loud Profanity = Good Code

Share this post


Link to post
Share on other sites
Guest Anonymous Poster
quote:
Original post by Extrarius
I don''t comment my code at all (well, once in a rare while I will, but usually comments are code that is temporarily removed).

So far, I''ve only had a single problem understanding my code and that was after almost a year away from it. If I had spent more time on the code, I could have made it more clear, but I wanted to get it done fast at the time so I threw in some hacks to add functionality. Now I don''t feel like rewriting it so I just spent about an hour figuring it out and adding a couple of lines of comments.

I agree with whoever said that if you need a lot of comments you are coding incorrectly. Class names, function names, and variable names should be descriptive enough to give the gist of what the code is doing. If you are using strange algorithms that aren''t easily understood, it would probably be better to include a reference to a document describing the algorithm.




The entire point of adding in comments to your code is to provide yourself and others with a refrence as to what your train of thought was at the specific time you wrote it. I can gaurentee 3 or 4 years from now if you look at the code you wrote today you''ll either think to yourself "What the hell was I thinking?" or "What does this do?".

Onto some other things....

Functions deserve their own comments for a number of reasons. First and foremost you may have an overloaded function how does this function differ from the other function? Why was it created? What does it do? And why should I use it instead of the other overloaded function? All these questions could be answered with a note under the function comments section, instead of forcing you to read through the functions themselves to see the differences. Also function comments can typically be seen through intellisence in visual C++ which allows you to view these notes with out having to actually goto the function itself, saving you time.

As for class names...
Again because of the possability that someone may choose the same class name as you have you should give a little description of what your class is/does and which headers/libraries are needed for it to compile correctly. This is obviously not to much to ask.

Typically variable names don''t need any specific comments. Unless of course your using names like "foo" and "bar". The need for comments on variables can be reduced dramatically with the use of some derrivitatve of hungarian notation.

Commenting isn''t a sign of "bad programming" it''s a sign of good programming practice. If you comment alot you can always remove un-needed coments at a later time. But if you don''t comment at all eventually you may end up either re-writing the entire peice of code, or having to go through the code & decypher what you once wrote and have long since forgotten.

Share this post


Link to post
Share on other sites
quote:
Original post by pan narrans
[...]
Surely there is a difference between relying on comments, and including them for the purposes of clarity (as a beginner, for potential employers, and for colleagues)?
Sure, but I think having 'function headers'(or class headers, header file headers, etc) is WAY too much commenting in my opinion. The name of a function, the names of its arguments, and a single line comment should be enough to make its purpose(and what it does, and probably even its side effects in most cases) clear.

Of course, if you are programming on a team, you'll need more comments than if you were the sole programmer, but I still think huge headers are too much. If you can't describe the function in 1-2 lines you are probably putting too much in the descripting. I've seen several files in open-source projects where the header details the algorithm used, the specific tricks used in the implementation, etc. All it needed to do was say what the result of calling the function is (like I said, put a link to a document on the algorithm, or put those comments inside the function on a section by section basis) because the caller of a function usually doesn't need to know how it works. Especially when using OO principles, classes and functions can (and usually should) be black boxes. Abstracting implementation from interface is (almost) always a good thing.

[edited by - Extrarius on March 24, 2003 12:32:47 PM]

Share this post


Link to post
Share on other sites
Guest Anonymous Poster
quote:
Original post by Extrarius
Sure, but I think having ''function headers''(or class headers, header file headers, etc) is WAY too much commenting in my opinion. The name of a function, the names of its arguments, and a single line comment should be enough to make its purpose(and what it does, and probably even its side effects in most cases) clear.

Of course, if you are programming on a team, you''ll need more comments than if you were the sole programmer, but I still think huge headers are too much. If you can''t describe the function in 1-2 lines you are probably putting too much in the descripting. I''ve seen several files in open-source projects where the header details the algorithm used, the specific tricks used in the implementation, etc. All it needed to do was say what the result of calling the function is (like I said, put a link to a document on the algorithm, or put those comments inside the function on a section by section basis) because the caller of a function usually doesn''t need to know how it works. Especially when using OO principles, classes and functions can (and usually should) be black boxes. Abstracting implementation from interface is (almost) always a good thing.

<SPAN CLASS=editedby>[edited by - Extrarius on March 24, 2003 12:32:47 PM]</SPAN>


Yes when using OO Principles thing should be a black box for the user however this black box theory should not be applied to those who are maintaining and updating the black box code itself.

Huge "file headers" are used to track the changes that have been made to the file. The dates that they were changed, and the user who had changed them. Granted you can remove this a tad by using some type of source control but it still serves a purpose.

Share this post


Link to post
Share on other sites
Well, when maintaining your Camera class, for ex, you shouldn''t need to know which engine you are using etc. You just need to know that the camera class sets up a matrix based on its inputs and sends the matrix to the renderer. In this sense, everything but the class you are maintaining is a black box to even you. Unless you are debugging inter-class communication, you shouldn''t need to know how the other classes work. There are of course exceptions, but in general that is how I think it should be.

Those few comments I said I use are usually things like implementation specific tricks of an algorithm, because those are the places hardest to understand (as they are often ''hacks'' to improve performance, they might not follow the algorithm in an obvious manner). If I used a bit field instead a closed list in A*, I might put a comment where the bitfield is defined, but it would be something like ''bitfield instead of closed list to track already visited nodes'' at most (more probably ''bitfield for closed list''). If you know the algorithm being implemented, it should generally be easy to understand the implementation if there are such comments (if I were commenting for somebody else, I might put a comment at the start of each step, like ''choose cheapest node in open list'')

Share this post


Link to post
Share on other sites