I have worked a few places which haven’t used source control. They seemed to get into the habit of putting comments around code they changed explaining the change so that things could be reverted.
I have found that this makes the code very difficult to read, and have been fairly adamant that such comments are not needed after introducing source control as the revision history will let you match up tickets with changes.
However now, I am not so sure, I think it may be good to document major revisions to a file in a file as well as in the commit messages. This should make the code more readable. Do people have a best practices way of documenting changes to code, so that it is not too cluttered but is still explanatory to someone trying to read it?
Just to be clear, I am not talking about a list of changes in the head of the file (which is a whole other argument) but comments in the code.
The documentation present in code should describe the code it is near. If the code changes, the documentation should also change accordingly. The version control system should take care of managing what changed and why it changed. Let the code and it’s documentation do it’s job (Doing things, and describing how/why those things are done), and let the version control system do it’s job (controlling/documenting versions and changes).
Whenever you start indicating history in the present(current code), you are asking for trouble. Just think what a particularly change-heavy area of code would look like if it had a number of changes?!