I don't remember a real life situation when I was unhappy because the code had so many comments. Several times I've been unhappy because the developer obviously

I don't remember a real life situation when I was unhappy because the code had so many comments. Several times I've been unhappy because the developer obviously had spend a lot of time thinking something, but did not leave any clues about his thought process in form of comments. Especially if the code is dense, it is not always easy to grasp the meaning. Sometimes the lack of comments leaves you to wonder if you are looking at a bug or a deliberate design decision. When working on projects that have history, one sad thing is that usually everything else gets lost over time except code and comments. Design docs, issue trackers, emails, commit logs - all gone when companies change, code is moved around etc. My general instruction would be that if you are thinking if you should write a comment, then write it. Writing a comment takes no time at all and it is easy to remove later. Coming up with the same insight that would be captured by one line comment may take hours when somebody else is looking the code 12 months later.