documentation of code changes and source control system

Question

what is common if working in a team of developers:

make special documentation that somebody introduced a method or changed a method (with his name or acronym)

///remark: introduced by sbd

///remark: changed on 12.12.08 by sbd

or not doing this at all? in my opinion it is not necessary because i can get this information out of the source control system. but maybe you have further informations for me...

edit: to clarify, i mean really only adding the personal and time information, not the information why something is there

Answer 1

There are several schools of thought about how to use source control, but the agile community (practicing continuous integration) tends to use small commits that represent a single change of functionality, not so fine grained as adding a new method. You can get that information out of source control using diffs, if you want.

Answer 2

Yes, I agree. Not necessary because any common source control system has this information. What may be necessary is an explanation as to why it was introduced or changed.

Answer 3

We don't do that. We use the DIFF tool in our Source Control provider if we want to see specific changes.

But if you have to meet SOX compliance or something you might have to annotate changes in code like that.

Answer 4

We used to do that, fallibly and sporadically. We invariably ended up looking in the source control system even if the comments existed. The process eventually wilted on the vine.

Answer 5

Extra annotation of this sort provides little value when you can get the same information from your SCM system. They waste the time of the person adding the comments and the reduce the code readability by adding more clutter.

Answer 6

One approach says that one should completely trust the version control tool, and use commit comments without leaving a trace in the code. However, readers of the code may not be aware of the changes, and not all source control systems let you see all the changes to a specific method over time (rather than whole file).

My view is that you should put the comments in if you want to increase the chances that a reader of the code will become aware of the change. If they don't need to stumble across it, it's not important enough to be in the code.

Answer 7

My problem with diff is that it tells you what changed, but not why. If a commit includes a lot of files then the commit comment may not detail why each file changed.

My experience of version control started with our Oracle PL/SQL code using SourceSafe. We had a change log in each file listing the issue number, developer and comment. Without that it was tricky to see when code had been added as you would have to search through the history to see when it changed.

Now we also have C# code with SVN. That provides much easier checking of history, including 'blame' view to see who added blocks of code. You can also see what other files were committed at the same time to see the context.

I'm still adapting to the SVN world. Perhaps it can give me adequate views to make change log in the files redundant, but I like to see comments in code that tell me why it as it is.