vrijdag 11 juli 2014

"You can read the code, right?"

A few weeks ago I talked to a programmer who insisted that you should not add comments inside your code to explain what you are doing. His argument was that this documentation will quickly get outdated as the code evolves, and incorrect documentation is worse than no documentation. Reading the code tells you exactly what the current code does. I asked him why he didn't just update the docs along with the code, but apparently that was just a silly question, he didn't write docs, end of story.

I've seen this kind of behaviour a few times before and always in bad programmers. Not just bad as in "he doesn't stick to convention", but bad as in "his software does not work". And why doesn't it work? Because he has no documentation to stick to. Every time he modifies a routine he has to think back to the time when he first created the routine, to try to remember what it is supposed to do. This works exactly once, and after a month he really does have to read the code.

But, the code does not tell him that there is another routine a somewhere else in the code, that requires that once IF statement so it will never return -1. So when a complaint comes in that the value -1 cannot be used, where is nothing stopping him from removing that, apparently useless, IF statement. a few days later it turns out that the other routine has been messing data up bigtime.

Yeah, let's not document routines, good idea.