How do you annotate code changes and code authorship

Question

What is the best way to annotate who authored a file and subsequent changes that were made?

I'm a contractor on a new project, one that's just starting, which is using Subversion. The other day I noticed a team member had updated a script written by an outside consultant, and he updated the header from "Written by X" to "Writen by Y and X" (since he had made a decent number of updates).

I didn't think this was a good idea, because others after us may update that script with small or large changes and it'd be unclear when to update the "Written by" header (or how to order the names). I pitched the way I had done it at my previous company (with an edit log at the top of each file - which was enforced by whoever verified the changes, we were using Clear Case so changes wouldn't be pushed up until they were verified), but then he mentioned we could just use the "svn log" command to see edits and it'd be hard to enforce an edit log.

So now I'm not so sure what the best way to annotate authorship and changes is. Files can completely change over time, so I don't like the idea of a stale "Written by" header. And a "Written by" header that just includes a long list of people with no context doesn't seem useful. There's removing the authorship header, and simply using the subversion change log, but then what do you do about "Written by" headers from code that's given to you (from consultants, old code bases, downloaded from the net, etc)? How do other teams handle this?

Answer 1

I'm with you, modern source control documents who did what to what in source code a lot better than some random comment in a header file.

Your customer is wrong, he is wasting time and adding garbage to his files. But he's still the customer.

If you are a contractor you ought to go with the client's coding standards.

If this is just an ego thing, just forget about header comments and do your job.

Answer 2

I don't like the idea of a stale "Written by" header.

Correct. It's useless.

And a "Written by" header that just includes a long list of people with no context doesn't seem useful.

Correct. They're all dead, BTW. Or won the lottery. They're at sea and cannot be contacted. Why list them?

My favorite is using initials. Added 12/7/91 SRP. Who's that? And how will you find out? If they were a contractor, you'd have to pull all the invoices from around that date, call all the contracting firms that are still in business so they can pull all their personnel records.

what do you do about "Written by" headers from code that's given to you (from consultants, old code bases, downloaded from the net, etc)?

Ignore it.

Answer 3

Let the SCM handle it. It's the only way to be sure the information is always up-to-date, it's granular to the source line level, and it's also the easiest way, since subversion tracks this information already. Even if you don't enforce commit messages, it's trivially easy to extract a revision number and accompanying changes from a blame, which should tell you all you need to know.

The only reason I can think of for wanting this information in comments is that svn blame or svn log are a bit slower than simply looking at the comments, but the price you pay for the tiny speed increase is that you have cruft in your code. The worst part, however, is that you're relying on manual processes for repetitive tasks.

Answer 4

I have to agree with Jim.

Any version control tool will do a better job than a large text blob at the top of a file. The version control system will be accurate, up to date and provide diffs dating back to the creation of the file. The header method will say:

11/01/98 - Redesigned file - KPR

04/15/05 - Patch to work around small bug - JSC

Comments should describe what a file/class/function/line does NOW. It's history is pointless to record in-line. It is a hold-over from the days before cheap/awesome version control.

You should explain to the client it will increase costs to do it that way and let that it would speed up development to let tools do the job properly.