Visual and Code

Genne has started to blog about coding, and thats great! Really nice to read, and his posts is full of enthusiasm. But, he came to the conclusion that one shouldn’t comment code. And thats wrong in my opinion. Here’s why.

Commenting code isn’t as much about pinning down knowledge, as it is communication. And when it comes to communication, redundancy is almost never a problem :) and you can never be clear enough. A well written method header and comments inside the method or function, is a much faster way of communicating the ideas and behavior of a method – for the people who maintains your code. And for the sake of misunderstanding.. I can see two major cases here. One, there are comments, but they are somewhat wrong because the code changed but not the documentation. The second case is no documentation at all. And then there’s the situation for the reader. He/She might misunderstand correct documentation (happens all the time), but can then try to read the code. Or, he/she reads the comments and they are faulty, and then tries to read the code. And in the third case, with no comments, the user must read the code, and, as well as before, the user may misunderstand or simply don’t get it.

And another thing, without documentation, I might misunderstand the code I’m reading and think that I find defects or suboptimal solutions.

And then there’s the case with APIs that you don’t have the code to… Ok ok, thats another story.

But hey, you can’t possibly mean that I shouldn’t document my Assembly code, do you? Super haxxor might read and understand ASM as I understand English, but the vast majority don’t.

Saying that documenting/commenting code is wrong, is saying ‘I don’t care if other people are able to read my code, and if they don’t understand their lazy and dumb’. And thats lazy and dumb :-)

So, of course, don’t comment/document every little simple thing, and mind that some documentation won’t be accurate / should be updated. But instead document what others need to know about your code.