Call For Input: Document Revision Comments
A little over a year ago we instituted a new policy within our dev team: placing a comment header at the top of every new (or revised) template. This comment header states what the template is, what it is used for, who originally created the file (if known) and a 'revision' listing. Every time a template is revised a notation was added to this header, with initials and date stamp, as to the purpose of the revision. This didn't replace line level comments to explain blocks of code, only augmented the process so that a total document change overview was available in an easy to review location.
Recently we finally moved to a version control system, Subversion. This is a huge step for us, that is long overdue, and allows us to finally begin working as an enterprise level team. Very important with a 3,000+ template system. But, currently I am in a minor debate with our Development Manager, as well as a few members of our team. They believe that we should no longer use our revision comment system, since Subversion is setup to require a comment on commit. Their argument is that you can easily pull the 'history' of a document from Subversion.
But, like any good team, the issue is open for debate. No one has layed down new policy in stone yet. I asked if I could put the question out to the community-at-large, to get an idea of how others handle this situation and try to learn from the experiences of those who've traveled this road before. How do you handle this? How would you/should you handle this?
At a previous job, we were basically putting the change note in the comment header, then copy-pasting it into the version control system. Tedious, but when we lost our version control database, we still had the history in the documents.
At the current job we use Rational ClearCase. (Not my choice.) We do the same thing, although I've been working with my CM to develop a way to put "tags" in our source code so that ClearCase can automagically add the comments, date/time stamp, and author to the source code without doing it manually.
I know other people have managed to do such a thing, but I don't know enough about Subversion. That would, I think, be the way to go.
With Subversion, you can easily get much better comments, and they are automatically attached to all the correct files. Moreover, they don't add clutter; you get to see them only when you want them.
Twice in the past, when moving older projects to Subversion, I've spent several days copying all those header notes into Subversion. It didn't get me the actual changes, of course, but it helped build a good audit trail of what changed when. In both cases, it turned out well worth it.
As to the comment about someone losing the VCS database, I'm assuming that your SVN repository is backed up nightly? That's all it takes to ensure the notes are safe.
Honestly, my basic rule of documentation is "Don't document the obvious", so if you version control system gives you who, when, and changes through the diff, then it seems like it would be a better use of time to write useful commit messages and some real comments instead of cut and paste that could be automated and is duplicated.
A little extra work, but it might make things faster in the long run.
Not because of that though :-) He decided to stop coming in to work about once every 3 days.
but if I had MY way it would have been because of the comments.
There is certainly the risk of out of sync page headers and the svn comments. Since the svn system enforces the use of comments, I would prefer to use that and leave the page level comments for description, a list of dependent resources and the like.
I know it is never easy retiring a process, once the process has proven its effectiveness, so I don't envy your quandary. That being said, it sounds like your development process is getting more sophisticated. Using SVN to its potential will streamline efforts and make it easier for the next developer to join the team.
Dan Wilson
We went through the same thing - we used to use Fusedocs and then a header that used the keyword expansion that John mentioned to actually embed the comments in the file (this was with cvs and the Log keyword) but often the comments would begin to take up to much space. Once we realised you could view the commit messages from right within Eclipse (right click->team->history) it became a no brainer to leave it to the source control system.
In your source code we keep comments designed for developers to use. Technical bits, perhaps line numbers where a particular change took place, etc. It's a lot easier on our developers to have comments and revision history available in the file they are working with rather than trying to traverse a source control system to find out what happened to the file on a technical level.
Example of source code header comment: "Added AJAX spell checking validation for the textarea fields. Lines 20, 268, 400"
In our source control system we keep comments which outline the spirit of the change. This allows us to quickly evaluate the reasoning behind the changes without having to know the technicalities of it.
Example of a source control comment: "Added spell checking functionality."
When in doubt, we try to err on the side of more documentation, not less. That approach has proven to be valuable to us on more than one occasion and on more than one project.
Good luck!