Code comments should explain why a particular piece of code is doing what it's doing right now, and what the expected behavior should be right now. Code should

Code comments should explain why a particular piece of code is doing what it's doing right now, and what the expected behavior should be right now. Code should be written so that comments are not necessary at all, but sometimes it's unavoidable. Now, why a particular piece of code came to be, why the code should have this expected behavior, why something is being added or removed or changed, may be unrelated (or unnecessary) to what this particular code is doing. So there's two kinds of documentation here: 1) "this is what this code does", 2) "here are the series of events that led to this code". You need the former when you are editing code. You need the latter when you are reviewing code for merge, as well as in the future to figure out how the f*!$ this code came to be (which is useful to avoid re-running into a bug, troubleshooting/understanding a legacy system, or removing important code). The latter may also immediately become obsolete the second time the same block of code is edited, so we keep this historic information in e-mail or code commit messages.