Do (not?) write comments

We all know a lot of jokes about comments and why not to write them. Even many articles suggest not to write comments. Why is that so?

I came on a project where the whole team left and now they hired me and two other developers. The project is one big mystery and there are only few people in the company who worked on it years ago and can help us. There is some documentation but no comments in the code. I suggested that when we go through the code and find out how it works, we write a comment. Then it came “Why comments?”, “Comments are evil.” “Even Clean Code book says it is bad.”, etc. What?! Something is really bad…

It is great when you want to improve yourself and read books and blogs, but do not take only a few parts from it and throw away the rest. Yes, comments are bad if they are outdated, or they contain lot of unnecessary text. Yes,they are evil if they say the code is doing something what it is not. Yes, the code should be self-documenting / self-describing.

But if so, why we have problems to read the existing code? Hmm… Maybe, we are not writing clean and self-documenting code.

Everyone, even the best of us, were beginners in the past. It is not bad to ask your colleague what he / she thinks about your solution. And if you are not sure everybody can read and understand it, write a comment. Descriptive one. Don’t be afraid, this does not mean your code has to be bad, also good code can have comments.