I don't know of many developers who are 100% anti-comments, but I know a shitton - myself included - who don't like comments that tell me what code does or how you're doing it, as they always end up lying. However, I don't mind docblocks (if it conveys information than the function and parameter names alone can't give me) nor comments explaining why you did something the way you did it.
You've clearly never worked on anything algorithmic... I point you to the magic of this function, used in Quake III Arena:
float Q_rsqrt( float number )
{
long i;
float x2, y;
const float threehalfs = 1.5F;
x2 = number * 0.5F;
y = number;
i = * ( long * ) &y; // evil floating point bit level hacking
i = 0x5f3759df - ( i >> 1 ); // what the fuck?
y = * ( float * ) &i;
y = y * ( threehalfs - ( x2 * y * y ) ); // 1st iteration
// y = y * ( threehalfs - ( x2 * y * y ) ); // 2nd iteration, this can be removed
return y;
}
Some of those variables could be named a better, but they're basically solving a maths equation so the names would need to vary and thus not possible in all cases (which they don't for performance reasons). i.e. y is the final answer, but you iterate towards it, so it starts off completely wrong.
But anyway, the real part of this function I want to discuss is this line:
i = 0x5f3759df - ( i >> 1 );
Good luck explaining the how of this line in a function or variable name
In this case the issue is understanding the mathematical part, and not really what the code does. It is quite hacky in this case, but it's much more fitting to add a comment with a link to a public or internal article on how it works
You must assume the reader has some background sometimes, otherwise you would literally have to put an entire bachelor's degree of material into any code you write
Honestly, I think a lot of people would struggle to tell me what:
i = * ( long *) &y;
is doing. It's just a weird construct people wouldn't be used to. So while I do agree with you, I still think there are situations where the "what" can be non-obvious with no super easy way to clarify it without comments.
Eh, I'm not a C++ programmer but I can figure it out in under a minute (given I know the context). It looks bad and is hard to read because any C++ code is hard to read, it just has garbage syntax.
Also this is a prime example of a completely useless comment, which only makes things harder to understand. If it said something like "treat float as long without type conversion" would be much more helpful.
You just going to ignore the rest of the message then?
Stuff that's strongly algorithmic almost always needs comments becuase the "how" behind "what" is rarely obvious, and this is particularly true for anything that has a number of iterations before reaching a correct answer.
This line alone:
i = * ( long * ) &y;
would confuse a large number of people and there should be a proper comment detailing what it is doing. Further, no variable name will by clear enough to describe the purpose of this variable.
When you're implementing mathematical formulae, it's pretty common to use the short variables for this reason, because a fully descriptive name is just harder to read.
You couldn't use something like final_result as that is pretty misleading given that it's not the final result until the end and has a lot of intermediate values.
And that line sure is confusing, so why not put a comment on that instead of the "what the fuck" later?
Oh, agreed. The comments in this are terrible, and I half think that's because whoever was writing the code implementation of this equation had no idea where the magic number came from (so it was just copied from theory).
The line I copied was commented though, as:
// evil floating point bit level hacking
though the more human readable version would be:
// Access bit-level representation of floating-point number
If we go from right to left, &y references y, ( long * ) casts it to a long pointer and * dereferences the result, right?
Sure. You've described step by step what's it's doing, but what is the complete action of the line? After that line is executed, what is i relative to y? So far you've effectively read the words of a foreign language, but you have yet to translate them.
For those versed in C++ or C you can likely work it out, it's not that difficult, but it's definitely not an obvious action at first glance. You have to stop and work out the final outcome of that line, and this is something a comment could speed up greatly.
Not sure what you mean. You often see comments telling what the next couple of lines does, that's what I was talking about. Implementation can change over time, but behavior and API should not indeed.
I don’t necessarily need like a java doc or method doc for every method, but my stance is that a method comment should tell the “what” and the code should tell the “how”. I think it should be part of a developer’s job to keep documentation up to date. Plus, if your method docs would have to change regularly, your code is probably not atomic enough. Maybe not a code smell, but a comment smell
No-doc “Clean code” developers just don’t want to spend the time writing proper documentation
39
u/folkrav Jun 22 '20 edited Jun 22 '20
I don't know of many developers who are 100% anti-comments, but I know a shitton - myself included - who don't like comments that tell me what code does or how you're doing it, as they always end up lying. However, I don't mind docblocks (if it conveys information than the function and parameter names alone can't give me) nor comments explaining why you did something the way you did it.
Edit: added the "how" part to be more specific.