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.
