Comment rot is like wiki rot -- all too common, and often more confusing. There are a couple good rules of thumb I follow. 1) If you are writing a comment, ma

Comment rot is like wiki rot -- all too common, and often more confusing. There are a couple good rules of thumb I follow. 1) If you are writing a comment, make sure it is a "why" and not a "what" (why this code exists, not a description of what it is doing). Why comments often survive refactoring, you might entirely redo the login system, but the reason you do it is still so people can log in. 2) If you find yourself documenting the "what" about code -- take a moment, and think really hard about why it is confusing. If it is accidental complexity (your fault), refactor it. If it is fundamental complexity (problem domain is a bitch), don't add the documentation to the function, put that knowledge in the tests. Nothing is as harmful that a bunch of gotchas buried in comments no one will read, and will eventually rot and not even make sense after the code is refactored.