I have often had the discussion with somebody about commenting code.

I have heard all the arguments:

• We need to comment code, so we can see what code we took out or changed.
• We need to comment code, so we can see who did this, when and why.
• We need to explain what this code does, so it is easy to understand for the next guy.
• …

I am sure there are many others, but it doesn’t change my view that COMMENTS ARE EVIL.

First of all Comments can be 1 of 3 things:

• Correct
• Misleading
• Out right wrong

Best case if of course that they are right. That is what we all strive for, but sadly rarely archive. In most cases they are misleading because the written language isn’t code and rarely clearly define what we really mean to say. It is simply too complex in many cases to say something described in the code in the written language without missing something. I guess that is why we write code and not novels. Then there is of course the case when comments are out right wrong because we forgot to update them or because we just wrote them down all wrong.

Generally Comments are just a way to hide bad code. The only true comment is the code and it should be written clearly and well-defined so it is easy for anybody else to read and understand. Always look back at your code. If it is hard to read and understand you should most likely rewrite it.

Then there are the arguments that we need to be able to see what we changed compared to the standard code form Microsoft. Just another excuse used by people that don’t use a proper source code management tool like Team Foundation Server or Visual Studio Online. The latter is free for up to 5 users and most of the job can be automated via PowerShell so there is really no excuse. The new tools we got to merge code from Microsoft in the form of PowerShell cmdlets also doesn’t need comments or the old code to work. More often these comments might actually confuse the tool.

Oh yes and then there of course is the arguments that we need to understand who did something and why. Again that is why you should use a complete tool like Team Foundation Server or Visual Studio Online where you can track and manage your development work. What exactly comes out of our development team? Track it both from your tasks and requirements to the code and back.

When it all comes down to it there is really no getting around it that COMMENTS ARE EVIL and we should try to do better.