The fact that documentation and comments can’t “fail” if the underlying code changes is a real problem. I’ve even worked at places which dictated that comments had to go directly above or even beside (inline) with the code they were explaining, so they would show up in any patches changing the code.

What do you think happened? Yup, people would change code and leave the outdated (and wrong) comment untouched, directly to the right of the code they just changed.

Hell, I was one of those people, so I get how it can happen.