Commenting your code – The sequel

As Ernst put it in the comments: we opened a can of worms here!
In my previous post about Commenting your code, I stated you should not comment your code. Of course, this is nonsense. The reason I stated that, however, isn’t. And I didn’t only say that because I would get some attention 😉

Too many times, I see complete useless naming of variables, classes, methods and so on. Because of this incomprehensible naming the developer who wrote the code then has to place enormous amounts of comments between his code to keep it even remotely understandable, even to himself. This way it becomes a completely unreadable mess. So I started out by saying: don’t comment. This is because I think it’s the first thing you have to keep in mind: write your code so it will be completely readable without any comments.

My next statement about commenting would be: pick comment-spots carefully. Sometimes you can’t choose method names, or that what you are trying to do is not easily readable from your code, whatever name you give to the diverse participants. Then and only then are you allowed to place comments in your code. This way, you minimize the amount of (useless) comments someone has to wrestle to, because in 80 percent of the time, your code will do the talking. The last 20 percent can be taken care of by comments, which you carefully added…

• dotnet