Cheers!

I believe it was in the book Clean Code by “Uncle Bob” where he explained that any time you have to leave a comment in your code, this is not something to be proud of, but it means you failed to express yourself sufficiently in the code itself. He was not saying that you should never have comments, but that you should try to make them unnecessary. When you can’t do this, comments are a necessary evil, not something to take pride in.

I do agree with you that the reason for a design decision something that needs to be commented more often than the meaning of your code.

I don’t normally use comments in this way, but if I am writing a complex algorithm, and I am struggling with it, I use this. However I would create a real method with the implementation missing with the comments inside the method. I would also attempt to make the actual code just as readable as the comments and then delete the comments. I have seen real code written for a commercial website where the comments were less readable than the code it was documenting.

I believe it was in the book Clean Code by “Uncle Bob” where he explained that any time you have to wite a commen

One example which happened on a project on the same client as me was related to the way objects were being queried from the database via Hibernate. The code was written in quite a hacky way to get around a performance problem and some guys decided to refactor it to the clean solution which was totally non-performant! Comments around that type of code would be really useful.

Another great article. I think we are tuned on this subject. Let me add some of my personal thoughts.

The topic reminded me of an old software maxim: “don’t debug comments, comments lie”. And why it is so? Because comments, like documentation, inevitably decays along time. This is the expected behavior of ‘live’ systems.

History tells that the strategy of ‘bringing documentation INTO the codebase’, via javadoc-like tools or via pure comment lines, unfortunately failed to solve the problem.

The assertive that “logic doesn’t change when translated from human language into a programming language” sounds a bit naive. A lot of questions can be raised, like ‘when translated in which programming language?’ or ‘in which style of programming?’ or ‘in which level of detail?’ or still ‘for how large and complex type of program?’

Going to the other extreme: a great article on XP tenets influenced me for a period of time. I have always been an advocate of TDD and intention-revealing coding, but then I was seduced by the siren song: no comments whatsoever. I have tried this path and I can say from my experience that it does not work either, not for large-scale distributed applications. Down the road, at some point, you will miss those concision hints that should have been sprinkled in the right places.

Today I believe that comments are necessary for the benefit of future generations, echoing the reasons and decisions of the past.

Actually, the ‘middle path’ is frequently the best.

Link to the article mentioned above: (I was surprised I could still find a reference) http://www.drdobbs.com/184414826;jsessionid=5XTLA3BFL4XOTQE1GHOSKHWATMY32JVN