[wcarss]

Comments almost always become lies with time, because code changes and nothing enforces that they are correct.

Having commentary built into the artifact that introduced the change ensures your commentary applies to the specific change introduced. It's then possible to tell why someone did a specific thing, and also to tell how things are today, and to decide if that justification still applies, or if things no longer match the description.

If you dig around a little bit, using e.g. the git pickaxe (-S), or github's excellent blame browsing tools, it's not that time consuming and you might find out some pretty surprising things.

[phailhaus]

> Comments almost always become lies with time, because code changes and nothing enforces that they are correct.

Maintaining comments is part of the job of the software engineer, to keep code understandable and maintainable by others on your team. If your comments are constantly going out of date, then either:

1. The team is not putting effort into keeping comments relevant for each other.

2. The comments are too far away from the code that they are referring to.

There's definitely a balance to strike between too many and too few comments, but comments are extremely important.

Commit messages describe why the code _changed_, not why the code is currently implemented in the way that it is. Those are two different pieces of information, and the latter should not be hidden away in a commit message that you have to go searching for. And if that code came from another file, it's extremely difficult to trace it back to the first time it was written.

Not only that, but how would this even work with the "atomic commits" requirement? Most of the time you can't change a single line and create a commit message explaining why that line changed, because it's not atomic. That line change happens in coordination with a bunch of other changes. How do you explain why one of those lines was implemented a certain way in your commit? It just doesn't work.

[idolaspecus]

I agree that maintaining comments is difficult and that they tend to drift. A good way to mitigate this problem is to explicitly include checking comments as part of the code review process.

I'm not saying you did this, but I think that most people who point out little issues with the mundane processes within software development haven't yet grokked the dev process in its totality. Commit messages, code reviews, comments, documentation, unit tests, design patterns and idioms, all these practices' strengths and use-cases compensate the others' weaknesses. I.e. to basically any gripe (again, not saying you griped) like "process X isn't worth it because of some maintenance issue" there's an answer along the lines of "well that's what process Y is for". Together all these processes produce high-quality codebases but when you lack one or more of them the whole thing falls apart quickly.