| > 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. |