I received this email today:
I bought your book “Teach yourself C++ in 1 Hour a Day” and on page 37 you say that “The bottom line is that comments should not say what is happening, they should say why it is happening”. Can you kindly elaborate this further?
The answer comes in two parts.
First, and to directly answer the question, it is the difference between writing
public void SomeFunction(object myObject)
{
// assign the cubic feet to a local variable
double cubicFeet = myObject.CubicFeet;
}
in which the comment adds no information at all, and in writing this:
public void SomeFunction(object myObject)
{
// create copy of the cubic feet
// property for local manipulation without
// modifying original value
double cubicFeet = myObject.CubicFeet;
}
although this is not an ideal example because if you know the rules of C++, then even this explanation is redundant. And that brings me to the second part of my answer.
If you assume your reader knows the language, and if you name your methods well and your variables well, I would argue that comments are (almost?) always redundant…
public void ManipulateCubicFeetLocally(object MyObject)
{
double cubicFeet = myObject.CubicFeet;
}
In this case, I can’t see the need for any comment at all. The name of the method and the variable make clear what the local variable is and what it is for.
This idea holds in C# as well as C++. of course.
The trivial examples are preventing you from making a very good and very important point. In particular it is vital to call out dependence on side effects:
//force LINQ to realise the result set so the connection can be closed immediately
var foo = bar.ToArray();
…(goes out of scope)
and technically challenging logic
//We are using matrix math to solve 8 linear equations in 8 vars.
//The built in matrix ops only support 3×3 but you can handle larger matrices
//with the following algorithm. If this math is unfamiliar to you
//then don’t fiddle with this method.
For what it’s worth, a comment on the “4 lines of code”. Long, long, LONG ago, I converted a PL/I program for the mainframe to one on the PC. The user wanted faster response time and so wanted it on the PC. It turned out that it was MUCH, MUCH slower on the PC. I found out that when I rewrote it, I refactored it into many small, 4 lines or so, procedures with very good names. So overall, the code was extremely readable.
However, it ended up spending almost all of its time establishing the setup of going into and out of those small routines (local stack variables, etc.). Basically the call instruction overhead was about 3 times the actual code. Consequently, it ran very slow.
So be cautious about making lots of very small routines that “don’t need comments”.
This makes perfect sense, but often times, nomenclature goes out the window in large apps and developers don’t follow consistent naming conventions and describing logic in the naming, so the redundancy is nice because you get a humanized and synopsized version of what they’re attempting to accomplish. I try and follow the “if the block is less than 4 lines of code, I typically don’t need to leave a comment” methodology and it works out pretty well.
Overall, good example though. It makes perfect sense and hopefully the person with the answer will understand your meaning better.
~Kevin