After reading a post about them in Korby Parnell's blog I have been playing around with couple of Visual SourceSafe (VSS) keywords $History: $ and $Log: $. These have the potential for being quite useful in documenting the changes to source code files.
If you haven't come across SourceSafe keywords before, they are little pieces of text you stick in your code. When you check the code in, SourceSafe replaces each keyword with version information. There are a whole load of them, but this post will concentrate on $History: $ and $Log: $.
Before keyword expansion can be used, a SourceSafe administrator has to enable it. This can be done either by using SourceSafe Administrator or by editing the srcsafe.ini.
The $History: $ and $Log: $ keywords give you practically the same information it is just the lay out that is different. An example of each in an XML file is given below.
<!--
$History: $
-->
<!--
$Log: $
-->
Expands to
<!--
$History: Keyword.vbs $
***************** Version 2 *****************
User: Mbrown Date: 14/10/03 Time: 14:36
Updated in $/Build Scripts
Check in comment goes here
***************** Version 1 *****************
User: Mbrown Date: 14/10/03 Time: 14:35
Created in $/Build Scripts
Check in comment goes here
-->
<!--
$Log: /Build Scripts/Keyword.vbs $
2 14/10/03 14:36 Mbrown
Check in comment goes here
1 14/10/03 14:35 Mbrown
Check in comment goes here
-->
As you can see SourceSafe adds an entry for each version giving the Version Number, Date, Time, Author and the Comment entered in the check-in dialog. There is one minor difference between the two: the $History: $ keyword gives the path of the file for each change. This can be useful if the file is shared. Personally I prefer the $History: $ as it looks neater.
I can hear you all saying 'that's fine for languages with block comments but what about languages that don't, like VB?'
There is a solution to this, but it is not obvious from the Visual SourceSafe help files as there is a mistake in them. The normal solution to this problem is to stick a comment character in front of the keyword. This, however, doesn't work for $History: $ and $Log: $ as they add whole new lines to your code. The solution to this is to add a [Keyword Comments] section to the SourceSafe Database's srcsafe.ini file. This file can be found in the root directory of the SourceSafe database.
The [Keword Comments] section allows you to associate a comment string with a file extension. Each extension can have two strings one that SourceSafe places before added lines and one that it places after. These strings are contained in quotes and separated by a comma. For example:
[Keyword Comments]
*.vb = "' "
*.cs = "// "
*.sql = "/* ", " */"
*.xml = ""