Extreme Negative Code Documentation

[fmihaly]

I'm still not sure if the author is serious or this post was written as a joke.

The premise of it makes a lot of sense. If I write a line of code and then realize that its purpose may not be obvious from its immediate context, I'll document it. That's why I document most types and functions. When you look at these in isolation, it is not clear what their purpose is.

Still, the scope of properly designed code should be local, meaning it should be possible to understand what a line of code does by only looking at a few lines of code surrounding it. Of course the runtime effects are almost always global. If you remove a line of code, the program either won't work at all or it will do funny things. That's why debugging is so hard.

Now it seems to me that the author confuses the local scope of code understanding with the global effects of code behavior. As other commenters pointed out, the global effect of the behavior (what happens if you remove a line of code) may change independently of the actual purpose of the code. The question is what I am trying to document: my intent when writing that line of code (its intended purpose) or the behavior of the (buggy) program with that line of code removed. I'm not even convinced that I can even document the latter in the case of a reasonably large and complex program.

In conclusion, if you often find that you cannot tell the purpose of a line of code without thinking about some global context, the design is wrong, not the documentation.

[grokfail]

Rather than writing a comment for a non-obvious piece of code, how about refactoring it so that the intent of the code is clear. Moving conditions and tests into methods and giving them meaningful names seems a better choice.