Community Pick: Many members of our community have endorsed this article.

Documenting changes to VB6 or VBA code

Martin LissKeep everyone healthy; Get Vaccinated
CERTIFIED EXPERT
Almost 50 years of programming experience. Click '+ More' in my "Full Biography" to see links to some articles I've written.
Published:
Updated:
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
                          'new
                          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

VB6
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.
AnnotateVB6.txt
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.

Excel
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.
AnnotateVBA.txt
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!
19
7,677 Views
Martin LissKeep everyone healthy; Get Vaccinated
CERTIFIED EXPERT
Almost 50 years of programming experience. Click '+ More' in my "Full Biography" to see links to some articles I've written.

Comments (11)

Martin LissKeep everyone healthy; Get Vaccinated
CERTIFIED EXPERT
Most Valuable Expert 2017
Distinguished Expert 2023

Author

Commented:
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.
Robert BerkeConsultant
CERTIFIED EXPERT

Commented:
Cool tool !! I would like to know how to make a similar tool, so I opened an EE question.

Thomas Zucker-ScharffSenior Data Analyst
CERTIFIED EXPERT

Commented:
Martin,

Thanks for pointing me to these articles, they are extremely helpful.  I definitely want to install the annotatevba dll you posted, but when I download it and rename it to a dll file (AnnotateVBA.dll) then try to run the regsvr32 command on it, I get this runtime error 0x80004005 .  Do you have any insight into this?

Thanks Again!
Martin LissKeep everyone healthy; Get Vaccinated
CERTIFIED EXPERT
Most Valuable Expert 2017
Distinguished Expert 2023

Author

Commented:
The dll can only be used in a 32 bit environment. If you'd like to talk more about this please send me an EE message.
Robert BerkeConsultant
CERTIFIED EXPERT

Commented:
Thanks Thomas for alerting me that  AnnotateVBA does not work with 64 bit Office.

Before i retired, I enjoyed using AnnotateVBA and I still use it occaisionally on my old 32 bit office laptop.

i am currently transitioning to 64 bit office 365  laptop so I am disappointed to learn that it will no longer work.

In past years I would have volunteered to aciively help Martin Liss upgrade to 64 bit, but sadly, it is no longer that valuable to this old retiree.

Martin: If you ever decide to upgrade, I would be glad to be an alpha tester.


View More

Have a question about something in this article? You can receive help directly from the article author. Sign up for a free trial to get started.