Selfelected

A great amount of comments might be a sign of lack of logic in the code.
Well structured code is easy to read and hence needs less comments. What should be commented is non obvious things.

My practical workflow is often like this: I write several lines of code.  I insert comments to explain, business wise, what is done, I realise I can refactor into method calls instead of comments and then my method names replace the comments.

Things to comment:
– many if statements have their origin in business rules. This is not obvious when writing/reading code deep down in the layers. Hence the need of comments.
– some coding becomes more elegant with delegates, nameless functions, pointers, inheritance or other tricks that are hard to understand for the not-so-experienced. These blocks of code or one-liners are easier to understand with some comment explaining.
– everything not visible on the screen might be unseen or forgotten. So if a piece of code has a requirement that is not visible in the close surroundings (visible or logical surroundings) a comment might help to keep the code on track.
– sidesteps from the normal path. As a sole developer or in a team one is supposed to follow a standard or normal-way-to-do-things. In those cases this standard is overruled a comment is good; the reason for sidestepping the standard.

I have true tale here:
I was working with damage control at a project and the air was sometimes a bit tense. Especially when the customer was around.
Now this customer asked us if the code was commented. This customer was a pain in the ass to work with and I didn’t feel like behaving so I answered that I thought the need for comments in code was a sigh of crappy coding. The customer didn’t share my point of view. My colleague didn’t either. He also tried to explain that comments are good. I held my fort.
Now to the fun part: My colleague didn’t write comments while I did.
And yes, I was called in because my colleagues code didn’t hold up.

Tags: code, comment, refactoring