Via Robert the Grey and Jesse Liberty, I have been thinking about code comments and how necessary they are, and I have come to the conclusion that some people have just never really written assembler.
Jesse’s argument for his project is as follows:
- Comments rust faster than code, even when you’re careful
- Well written code can be read, and comments are annoying footnotes
- Comments make for lazy coding
Comments rust faster than code not because you’re not careful, but because you’re lazy. And if you are lazy about commenting, how do I know you’re not lazy about coding?
I realise that sometimes the logic behind a piece of code can be less than clear; no matter how well you construct your variable and procedure names, that problem does not go away.
According to Robert:
- Stating the bleedin’ obvious (I’m looking at you Method Arguments)
- Put there because you’re too lazy to refactor the code as demonstrated in Jesse’s article and the comments
- Enforced by stupid corporate coding standard mandates that are still stuck in the 90s
- Stale (and sometimes actively harmful) by the next check-in or 6 months later
I think that this is a lazy approach. It says “I cannot be bothered to document things properly so it’s someone else’s fault if they do not/cannot read my wonderfully elegant code that is self-evident because I have designed it to be so”.
It’s also my experience that well written code tends to be accompanied by well-written comments, and that poorly commented code is rarely wonderful and easy to extract some meaning from.
If either Jesse or Robert want to carry out thought experiments like this, it’s entirely up to them. But in the real world, code standards should include checks for adequate documentation so that people, other people, have a fighting chance of dealing with other people’s elegant code. Just because you think you’ve written good code and it is self-evident what it is doing does not mean you actually succeeded in doing so.
I’ve no objection against the new generation languages. Anything that makes programming more accessible to other people is a good thing. Anything, however, that allows you to break down some discipline, is not a good thing.
If you’re disciplined enough to write good code, I honestly don’t see an argument for not being disciplined enough to write good documentation for said code. If you can’t then, in my view, it is lazy.