Commenting code - completely useless?
Author
I'd like to think not... but I've been learning a lot about agile dev lately, and Refactoring mentions that comments are a good indicator that a refactoring would be useful, even if it's just to extract a single line of code into a function with a clearer name. This makes sense, and all is well and good from here. Furthermore the source code of an entire project (or subsystem or once in a while even class) might not always be self-explanatory, but for something like that I would think you'd want to collect it in some other documentation (whether external or interwoven a la Literate Programming, something a bit bigger than //). I haven't yet started applying refactoring in my own code, so I've got the theory but not the practice -- can anyone offer an example or two of when comments are warranted vs. the alternatives?
Thanks
It is an interesting point as a perfect bit of code would be written in such a way that it reads like English and hence needs no comments e.g. instead of writing:
// Fire the bullet
DoStuff()
you write
FireTheBullet()
it now needs no comment. Of course a very obvious example but it bears up in most cases. Whenever you write a comment in a function you are explaining something or maybe reminding yourself to do something. In the first case better naming of functions and variables will often do away with the need for a comment and in the second a proper to do tracking system is preferred.
I put comments above functions (using Doxygen notation) that can then help create automatic documentation but I avoid all comfents in functions as, like you say, they tend to indicate something that could be refactored.
A lot comes down to naming things correctly. Call your functions exactly what they do and do not worry about long names - nowadays with all the intellisense features in IDEs you rarely have to type out a whole name anyway. e.g. instead of
CalcTraj()
write
CalculateTrajectory()
Proper naming also allows you to spot refactorings, e.g. if you find you are putting an 'and' in the name it usually means you need two functions eg.
FireBulletAndCheckForCollision()
Should be split into two functions (refactors) and then called like:
FireBullet();
CheckForCollision();
The same goes for variable names. Always name a variable exactly what it is! If you are unsure then you are not clear on your own design and need to sort that out first. This also prevents the horrendous activity of reusing variables e.g. temp
Another use of comments may be to say 'only ever call this function with a valid pointer'. Again rather than put the comment up enforce it. e.g. in this case I would put in an assert:
assert(pointer!=0);
You need to be clear what you want to code, clear on the restrictions of each function and the one taks the function does and then name the function correctly, enforce the restrictions via error tests and verbosely name your variables etc.
Anyway an interesting topic... :)
// Fire the bullet
DoStuff()
you write
FireTheBullet()
it now needs no comment. Of course a very obvious example but it bears up in most cases. Whenever you write a comment in a function you are explaining something or maybe reminding yourself to do something. In the first case better naming of functions and variables will often do away with the need for a comment and in the second a proper to do tracking system is preferred.
I put comments above functions (using Doxygen notation) that can then help create automatic documentation but I avoid all comfents in functions as, like you say, they tend to indicate something that could be refactored.
A lot comes down to naming things correctly. Call your functions exactly what they do and do not worry about long names - nowadays with all the intellisense features in IDEs you rarely have to type out a whole name anyway. e.g. instead of
CalcTraj()
write
CalculateTrajectory()
Proper naming also allows you to spot refactorings, e.g. if you find you are putting an 'and' in the name it usually means you need two functions eg.
FireBulletAndCheckForCollision()
Should be split into two functions (refactors) and then called like:
FireBullet();
CheckForCollision();
The same goes for variable names. Always name a variable exactly what it is! If you are unsure then you are not clear on your own design and need to sort that out first. This also prevents the horrendous activity of reusing variables e.g. temp
Another use of comments may be to say 'only ever call this function with a valid pointer'. Again rather than put the comment up enforce it. e.g. in this case I would put in an assert:
assert(pointer!=0);
You need to be clear what you want to code, clear on the restrictions of each function and the one taks the function does and then name the function correctly, enforce the restrictions via error tests and verbosely name your variables etc.
Anyway an interesting topic... :)
Well, I think that if some capability has been included in a language, then its for a good reason.
I believe that commenting every single line of code is, by and large, 'useless'. If you need to do that in order to understand your code, then its a good indication that it should be broken up into smaller, more manageable pieces.
However, a single comment for a block of code, a function or a module, is completely warranted. You can only gain so much by simply reading the name of a function or module. The comments should give an extra level of detail concerning the code's function and its use. Rather than trying to interpret several dozen (or more) lines of a code, reading a simple, clear and concise comment can save you loads of time when working on a larger project.
If the documentation is external, than I've got to always have that documentation open, switch to it when I need the information, and then search for the appropriate location in the document. Its much easier and faster when its right there. I'm not saying external documentation isn't helpful; it can be very helpful. But the two should probably be working in conjunction to provide the programmer what they need.
I believe that commenting every single line of code is, by and large, 'useless'. If you need to do that in order to understand your code, then its a good indication that it should be broken up into smaller, more manageable pieces.
However, a single comment for a block of code, a function or a module, is completely warranted. You can only gain so much by simply reading the name of a function or module. The comments should give an extra level of detail concerning the code's function and its use. Rather than trying to interpret several dozen (or more) lines of a code, reading a simple, clear and concise comment can save you loads of time when working on a larger project.
If the documentation is external, than I've got to always have that documentation open, switch to it when I need the information, and then search for the appropriate location in the document. Its much easier and faster when its right there. I'm not saying external documentation isn't helpful; it can be very helpful. But the two should probably be working in conjunction to provide the programmer what they need.
You may want to take a look at Javadoc or Doxygen. Those tools can generate documentation based on your comments.
basically you add descriptive comments above each class and method.
looking something like this:
even if the comments might seem slightly redundant it does result in pretty impressive documentation (Fully browsable html covering all classes and methods in your project).
basically you add descriptive comments above each class and method.
looking something like this:
/** * a normal member taking two arguments and returning an integer value. * @param a an integer argument. * @param s a constant character pointer. * @see Test() * @see ~Test() * @see testMeToo() * @see publicVar() * @return The test results */int testMe(int a,const char *s);even if the comments might seem slightly redundant it does result in pretty impressive documentation (Fully browsable html covering all classes and methods in your project).
Simian: Doxygen can generate most of that information without special comments. I can build references of where your function is called as well.
// StartPage should be called before DrawPageassert ($skeleton_status === SKELETON_ACTIVE);
My failed assertion handler in PHP automatically displays the line of code with the error, as well as the preceding comment (and a backtrace), making error messages simpler to understand than only file-line information.// TODO: replace with actual function once it's doneMockDisplay();
During development, in-code notes from programmer to programmer (and information about how to resume work) are very useful. Arguably, quite less so during maintenance.(* Little optimization trick: keep the pair *)| (x,0) as p when x > 0 -> right(p)
Small code-level information might not deserve moving to its own function (especially since it's usually a small modification), but it's interesting to leave behind for the less clever programmers.// Foo's algorithm: after the loop, store is never nullassert (store);return *store;
Although the overall algorithm may be described in detail in paper X, properties such as the above are best repeated in a comment, so that someone who does not wish to wade through an entire page of properties still understands why the function "magically" expects the store to be non-null.
Yeah sure ideally we'd never need comments, but ideally we'd only to write simple code like FireZeMeeesiles(). You're going to have to use comments a lot of times when there's no easier way to quickly tell what an algorithm does, or when it's not efficient to wrap a piece of code into a easy-to-read-function.
I only use comments though because it makes my code more colorful, green and friendly. Makes it feel alive.
I only use comments though because it makes my code more colorful, green and friendly. Makes it feel alive.
I like to think that the majority of my code is easily understandable, so I use comments quite sparingly. I do however think they are extremely useful for separating out blocks of code, just so at a glance I can tell which block does what if I'm scrolling through a page. I prefer that to having a large chunk of code in a single code block, or just separating with whitespace.
Ideals and reality rarely see eye-to-eye.
Architectures with complex template schemes, hierarchies, and special cases usually benenfit from a little comment blurb explaining how and why they work the way they do.
Even for a well-named and coded function, comments can help to clarify what is going on, especially for mathmatical or physics algorithms that other coders may not be familiar with.
Comments are usually a good idea when answers to the questions "why" or "how" about a particular piece of code are not immediately obvious.
Think about something like bump mapping and all the steps involved with it. It might make perfect sense to you, and the technique might even be well known to someone else, but how you implement it in actual code might be confusing to someone that didn't write it. It might even be confusing to you if you come back to it 4 or 5 months later.
Architectures with complex template schemes, hierarchies, and special cases usually benenfit from a little comment blurb explaining how and why they work the way they do.
Even for a well-named and coded function, comments can help to clarify what is going on, especially for mathmatical or physics algorithms that other coders may not be familiar with.
Comments are usually a good idea when answers to the questions "why" or "how" about a particular piece of code are not immediately obvious.
Think about something like bump mapping and all the steps involved with it. It might make perfect sense to you, and the technique might even be well known to someone else, but how you implement it in actual code might be confusing to someone that didn't write it. It might even be confusing to you if you come back to it 4 or 5 months later.
The one thing that I think that should be commented but almost never is; the legal values for all paramters. Can you have a null for that? are negative numbers ok? Will an empty string break things.
Doing this helps the testers and also helps people that use your functions.
theTroll
Doing this helps the testers and also helps people that use your functions.
theTroll
This topic is closed to new replies.
Advertisement
Popular Topics
Advertisement
