Re:Should I Comment My Code? The Case Against Code Comments
by jordanhudgens on Thursday October 06, 2016 @09:37AM
(#12652309)
Yes, the problem that I've found is that I've taken over legacy applications (several times), where the previous developer wrote comments/instructions for how to work with a method. And I wasted countless hours trying to follow their instructions, just for it to turn out that they had changed the method and never updated the comments. So the time wasting component can work both ways in my experience.
If that were an isolated incident I would blame it on the individual developer, however it's been a constant trend in the apps I've taken over through the years.
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.