Documenting changes to VB6 or VBA code

Published on
13,366 Points
15 Endorsements
Last Modified:
Martin Liss
Over 40 years of programming experience. Expand my "Full Biography" to see links to some articles I've written.
When changes need to be made to code, the easiest thing to do is obviously to just add, change or delete lines and be done with it. The problem with that is that after making several modifications you may find that you need to undo something you did and it may be difficult to remember what changes were made. It can also be difficult to remember why and/or when you made the changes.

I learned by experience that the easy method is not the best method and so I started annotating my changes like the following...

where this is the original code
    gbQuit = True
    frmProject.lblCounting.Caption = "Quit command accepted..."
    frmProject.tbarProject.Buttons(3).Enabled = False
    mnuPrint.Enabled = False

Open in new window

and this is the modified code.
    gbQuit = True
    frmProject.lblCounting.Caption = "Quit command accepted..."
    'frmProject.tbarProject.Buttons(3).Enabled = False
    frmProject.tbarProject.Buttons(4).Enabled = False

    mnuPrint.Enabled = False

Open in new window

That would indicate to me that I changed the line that refers to the 'Buttons' and showed me what is was before, and the blank line indicated that the change ended on the line above it. That's all well and good but it doesn't help resolve the why and when issue.

My annotation scheme now includes two ingredients.

Part 1.
I add a module named ChangeLog to every project. The contents of ChangeLog always look something like the following. For certain projects there may be a Programmer Name column and/or other data, but the actual format isn't important as long as the why and when information is included.

Option Explicit

'*                                                          CHANGE LOG                                                         *
'Release   Date      Change Description
'-------   --------  -------------------------------------------------------------
'01.00     07/07/08  (a) Initial release
'01.10     07/15/08  (a) Several changes to zoom function including:
'                        - Prevent zoomed image from becoming too large, or smaller than
'                          original size
'                        - Ctrl_r = re-center
'                        - Magnifying glass cursor
'                    (b) Found a second camera manufacturers comment,
'                        so created frmComment dialog, gcolExclude (comments to be excluded),
'                        and mnuComments
'                    (c) Corrected problems when app closed in "Full Screen" mode
'01.20     07/25/08  (a) Added crop function
'                    (b) Added tooltips to frmDisplay
'                    (c) Corrected a problem where the same starting tooltip was always shown
'                        depending on how they were handled

Part 2.
I've developed add-ins for both VB6 and Excel VBA that allow for easy code annotation. The VBA version probably works for other Office applications in addition to Excel but I haven't tried it. Please leave a comment to let me know if you were successful or not.

Once installed and turned on (see instructions below), this toolbar will appear. Excel users note: This toolbar will appear in the Visual Basic toolbar, not in the workbook ribbon or in the workbook Add-Ins drop-down.
Annotate Add-in ToolbarFrom left to right the first three buttons are:
Annotate Selected Text

Set Descriptive Text

Set Templates
Those buttons allow me to quite easily relate the code changes to the notes in ChangeLog. A typical annotation will look like this which was a change associated with change 'a' (Added crop function) of release 01.20.

    '******* 01.20a Start *******
    ' Initialize zoom parameters
    mintZoomClicks = 0
    ReDim mDimensions(1 To 15) As ImageDimensions
    '******* 01.20a End *********

Open in new window

After writing the two lines of actual code and adding the comment (like every good programmer does), the steps that resulted in the annotation were:

1. This step just needs to be done just once as it is saved for all programming sessions. Click the 'Set Templates' button which will show you this window.
Set TemplatesI entered ''******* % Start *******'  for the 'Start Template' and ''******* % End *********' for the "End Template' years ago and made them the defaults. You can enter whatever text that you would like to see in the header and footer on the annotation. You'll notice the '%' in each line. That gets replaced by whatever you set as your Descriptive Text (see 2 below). You can change the templates anytime you like but once you have what you like there's no requirement to enter or change it anymore.

2. Click the 'Set Descriptive Text' button which will show you this window
Enter-descriptive-text.jpgHere is where you enter the text the replaces the "%" in the templates. I entered '01.20a' in preparation for working on that change.

3. Finally, just highlight the lines that you added or changed and press the 'Annotate' button and you'll get something like my annotation shown above.

When you close Excel or VB6 and you've changed the descriptive text you'll see a message like this:
Descriptive Text changedIf you click 'Yes' the Descriptive Text will be saved and used as the default the next time.

I haven't mentioned the other two buttons yet because they have nothing to do with annotation. You can consider them a bonus and they are:
Clear Immediate Window

Close other IDE Windows
The function of the first is as it says, to clear the Immediate Window. I know you can select all the text in the Immediate Window or type Ctrl+A and then 'delete', but clicking one button is easier. The second one comes in handy when you have a lot of windows open and you want to clear up the clutter. Clicking the button closes all the windows with the exception of the one that has the focus.

Installing the Add-Ins

Download the AnnotateVB6.txt attachment and change the name to AnnotateVB6.dll. It doesn't matter where you store it. Once you have the file renamed you need to register the dll. To do that go to Start|Run and enter regsvr32 C:\AnnotateVB6.dll on the 'Open:' line and press OK. You should get a message saying that the registration was successful.
The final step is to go to the VB6 IDE and select the Add-Ins|Add-In Manager… menu item and select 'AnnotateVB6' from the list. Under 'Load Behavior I suggest selecting both available options.

Download the AnnotateVBA.txt attachment and change the name to AnnotateVBA.dll. It doesn't matter where you store it. Once you have the file renamed you need to register the dll. To do that go to Start|Run and enter regsvr32 C:\AnnotateVBA.dll on the 'Open:' line and press OK. You should get a message saying that the registration was successful.
The final step is to go to the Excel VBE and select the Add-Ins|Add-In Manager… menu item and select 'AnnotateVBA' from the list. Under 'Load Behavior I suggest selecting both available options.

Note that while this is a COM add-in you won't see it listed if you go to either File|Options|Add-Ins|COM Add-Ins (or Excel Add-ins).
If you find that this article has been helpful, please click the “thumb’s up” button below. Doing so lets me know what is valuable for EE members and provides direction for future articles. It also provides me with positive feedback in the form of a few points. Thanks!
Author:Martin Liss

Expert Comment

by:Christopher Wright
Downloaded this add-in and it worked.  Very nice tool to isolate changes/modifications to code by multiple users as well as solo projects.  Good stuff Marty!  Very impressive and quite useful might I add.
LVL 53

Author Comment

by:Martin Liss

Expert Comment

Useful article Martin, is there any reason you don't use versioning? Since modules, forms and classes can easily be exported as text files, I've always found it useful to use something like TortoiseSVN to properly document changes. The advantage of this approach is that all changes are documented, previous versions can be compared side by side with other versions and it is trivial to roll back to a given commit.

Of course I'm not suggesting that this should take the place of properly documented code, but I find both approaches used together extremely useful.
Ultimate Tool Kit for Technology Solution Provider

Broken down into practical pointers and step-by-step instructions, the IT Service Excellence Tool Kit delivers expert advice for technology solution providers. Get your free copy now.

LVL 53

Author Comment

by:Martin Liss
Version 1.1 - Fixed a small bug that resulted in one less line being shown as selected after the 'Annotate Selected Text' button was clicked, as compared to before it was clicked.
LVL 32

Expert Comment

by:Daniel Wilson
Good thoughts here. I have gone from no change documentation to my initials and date on every line changed to relying primarily on Git for my change log.  I haven't found anything with the right balance of information and clutter.

Expert Comment

Hi Martin
I wish I'd found this earlier, its great - thanks.
I confirm that the dll worked first time in Visio 2013. When I opened the app, the toolbar was in place, and it worked as in excel.

However, I wish I had taken more notice of your guidance: "Note that while this is a COM add-in you won't see it listed if you go to either File|Options|Add-Ins|COM Add-Ins (or Excel Add-ins)." Then I'd not have spent time searching for it in the visio Trust Centre!

One suggestion,
I tend to add date and time to my my annotations (DDMMYYYY hh:mm, ).  I realise you have this in the Change Log, but sometimes I find it helpful to have the date & time in situ in the code.

Could 'Set descriptive text' button cause to add Date & Time  between 'START' and the trailing '*****' template text?

LVL 53

Author Comment

by:Martin Liss
You can enter anything you like manually but if you are asking if it could automatically reflect the current date and time there's no provision for doing that. If you want to discuss this further please use the "Ask a Question" button that you'll find at the bottom of the article or send me a normal EE message.

Featured Post

Cloud Class® Course: Amazon Web Services - Basic

Are you thinking about creating an Amazon Web Services account for your business? Not sure where to start? In this course you’ll get an overview of the history of AWS and take a tour of their user interface.

Join & Write a Comment

This Micro Tutorial will demonstrate how to use longer labels with horizontal bar charts instead of the vertical column chart.
Many functions in Excel can make decisions. The most simple of these is the IF function: it returns a value depending on whether a condition you describe is true or false. Once you get the hang of using the IF function, you will find it easier to us…

Keep in touch with Experts Exchange

Tech news and trends delivered to your inbox every month