Best practices for writing code comments
I write my comments in commit messages because those are valid forever. A lot of times somebody will write a code comment, the code will be changed, but the comment not. This is a huge waste of time on so many fronts: writing the comment in the first place, and then confusing the subsequent developers with the wrong information. If you truly want to understand something, you can always check the change log, and find out why things are how they are.<p>Exceptions are e.g. if it's something exceptionally tricky or a hack of some kind that is kind of important. It doesn't happen all that much because the stuff I work on is simple. If I was going to do a lot of "commenting" I would prefer to write and update good documentation that gives an overview of how different things work together. The nitty gritty changes too often and is not that important in the grand scheme of things.