why-document-code.md

Excerpts from this discussion: https://news.ycombinator.com/item?id=12818016

Take this strawman for instance, how could you find the bug in the following code without the accompanying comment?

// Print every other line of the array to the console
for (var i = 0; i < myStringArray.length; i++) {
    console.log(myStringArray[i]);
}

This shows how important intent is to a program. Yes, the example is trivial, but without that comment, how would we know that it's wrong?

Because the problem with that is that now you have two competing sources of authority -- the comment, and the code. One of them is right and one of them is wrong. But which is the right one?

In the real world, the answer is almost always "the code that's actually been executing, rather than the comment that hasn't," which is why it's a good idea to minimize commentry of that type, to prevent confusion on the part of the reader.

what if it were a method name instead of a comment?

function printEveryOtherLine(myStringArray) {
    for (var i = 0; i < myStringArray.length; i++) {
        console.log(myStringArray[i]);
    }
}

Is your argument that the method name is incorrect because the code dictates a different behavior?

This is the almost the same example. Function names also don't execute. The parent's point was that if the code has been tested or was considered working, and then you noticed this in the code, you should think twice before "fixing" the behavior to match the comment or function name.

Then why even name anything? Are you saying I should just name my functions and variables a, b, c, d, etc.?

That's an extreme position. Function names are a valuable hint of what the function is supposed to do. But if the name doesn't match the implementation, which one is wrong? We don't know.

But you do know something might be off, which is better than not knowing when something is off.

"Redundant encoding" isn't a way to automatically fix errors, but rather only a way to detect errors. Like a one-bit Error Correcting Code: the fact that the parity bit is wrong tells you something is corrupt, but it doesn't let you know what the right value should be. There's one useful thing you can avoid doing in response to such an error being detected: not rely blindly on either the implementation or the specification being correct, but instead check them both.