A Philosophy of Software Design

by John Ousterhout

The best way to ensure that comments get updated is to position them close to the code they describe, so developers will see them when they change the code.