Are Comments Unnecessary?

Warning! Some information on this page is older than 6 years now. I keep it for reference, but it probably doesn't reflect my current knowledge and beliefs.

Sat
08
Sep 2012

I generally believe that in programming there is often only one right way of thinking and who doesn't agree with it is just not experienced enough to understand it. That's why I avoid expressing my personal and more "philosophical" opinions about programming. But maybe I should? Tell me what you think in comments.

I was inspired to write this post by the list of 20 controversial programming opinions. It looks like a gist from discussion of many professionals. I like it a lot and agree with all of the points, except one.

In point 4 they claim that comments are a form of code duplication and should be avoided in favor of more readable code. I don't think that's true. In the perfect world all code comments would be unnecesary because programming language would be so clean and expressive that we could express our intentions directly in the code. But in reality there is always lots of bookkeeping / boilerplate code that we have to interlace with real logic to make any program work. Managed languages (like C#, Java) and scripting languages (like JavaScript, Python) do better job in reducing it than C and C++, but in exchange for performance.

Look at this very simple example. HLSL language has function reflect that calculates a reflected vector. If it didn't, we could easily code it in HLSL using vector arithmetic, like this:

float3 reflect(float3 i, float3 n) {
    return i - 2 * dot(i, n) * n;
}

Now what if we want to code same function in C or C++ and we use XNA Math as the math library? It would look like this:

XMVECTOR reflect(FXMVECTOR i, FXMVECTOR n) {
    return XMVectorSubtract(i, XMVectorScale(n, 2.f * XMVectorGetX(XMVector3Dot(i, n))));
}

Much better than if we coded it using D3DX math functions, but still not very readable. Don't you think that the formula for this calculation, expressed directly in some comment above this function, would help to understand it?

// i - 2 * dot(i, n) * n

Please also recall how algorithms look like when described in this Pascal-like pseudocode in computer science books. Now think about an algorithm for manipulating some complex data structure that you seen or written in the real code. Was it similar? I bet it was several times longer because of all this memory allocation and other stuff that had to be done to make it a working code.

Of course I agree comments that repeat what can already be seen in code are stupid.

// Creates thread.
void CreateThread();
// Number of threads.
UINT threadCount;

Even worse when comments replace good identifier names.

// Creates thread.
void Go();
// Number of threads.
UINT i;

But code doesn't tell everything. It doesn't tell whether particular pointer can or cannot be null, a time value is in seconds or milliseconds, a number has to be power of two etc. I like comments before functions and classes, especially in header files, as a form of documentation - no matter if in Doxygen format or not.

/*
i - Incident 3D vector, pointing towards the surface.
n - Normal 3D vector, perpendicular to the surface. Should be normalized.
Returned 3D vector points from the surface.
*/
XMVECTOR reflect(FXMVECTOR i, FXMVECTOR n);

I think encapsulation is everything. Even in real life, you press buttons on any device and use it without need to know all the electrical and mechanical details about what happens inside the box. In programming we want to use libraries, classes and functions just by using its public interface, without studying the underlying implementation. Hey, if we had to always deal with all the details down to the lowest level, we would never be able to build any complex system! Similarly, I'd like to see the mathematical formula or algorithm pseudocode without studying all the boilerplate that's in the real code. That's what documentation is for, that's what comments are for. And that's why I hate this saying "Want documentation? Just look at the code!"

Comments | #philosophy Share

Comments

[Download] [Dropbox] [pub] [Mirror] [Privacy policy]
Copyright © 2004-2024