Help / Tour

Document Module Document Procedure Insert Timestamp Insert Template Close Windows Close Immediate Window Insert Error Handler Insert Error Handler Insert Error Handler Clean Variables Clean Variables Smart Indent Smart Indent Smart Tab Order ZOrder Management Project Statistics Tidy White Space Tidy White Space Procedure List

VBCodeHelper creates its own menu, and adds up to 18 buttons and a combo box to its own toolbar within the Visual Basic IDE. A configuration program that is available from the Windows Start menu or VBCodeHelper menu is used to tailor the Add-In for your own requirements. The following functions are provided:

  Document Entire Module (Hot key: CTRL+SHIFT+M):
This button adds user-defined boilerplates to the top of the current code window and to each procedure. This gives you the advantage of quick and consistent documentation of all your code. "Tokens" can be included within the user-defined template that are replaced with the appropriate value when inserted (see the token list below). In addition, the user can define their own tokens for replacement in boilerplates and templates.

Procedure templates are added either just before the procedure declaration line or just after it depending on the setting in the configuration program. VBCodeHelper assumes that the procedure has already been documented if there is a comment line before the declaration or after the declaration respectively.

Uses the boilerplates HEADER_SUB.tld, HEADER_FUNCTION.tld, HEADER_SET.tld, HEADER_LET.tld, HEADER_GET.tld and HEADER_MODULE.tld as appropriate. The boilerplates are stored in a directory as defined by the user with the configuration utility. User-defined tokens are stored in a file named USER_TOKENS.dat and stored in a directory as defined by the user with the configuration utility.

  Document Procedure (Hot key: CTRL+SHIFT+P):
This button works similarly to "Document Entire Module" except it only effects the current procedure in the code window, or if in the declaration section, it inserts a module header.

Procedure templates are added either just before the procedure declaration line or just after it depending on the setting in the configuration program. VBCodeHelper assumes that the procedure has already been documented if there is a comment line before the declaration or after the declaration respectively.

Uses the boilerplates HEADER_SUB.tld, HEADER_FUNCTION.tld, HEADER_SET.tld, HEADER_LET.tld, HEADER_GET.tld and HEADER_MODULE.tld as appropriate. The boilerplates are stored in a directory as defined by the user with the configuration utility.

The standard boilerplates included with the application are based on the style of error handling that we usually use in Frez Systems projects and are dependant on a module level constant being entered manually in each module called MODULE_NAME to define the name of the module, and two functions usually placed in a standard module called FormatErrorSource and ShowUnexpectedError (you can use the VBCodeHelper template insertion tool to insert these two functions by choosing the ERROR_UTILITIES.tlt template.

You can quickly insert the MODULE_NAME constant by using a template for the purpose, or alteratively, you can remove the requirement for the constant by replacing the code:

     MODULE_NAME

in the templates with the code:

     “%MODULE%”

However, if you use %MODULE% to insert the module name you will have to update the text should you copy or move the procedure to a different module.

  Insert Time Stamp (Hot key: CTRL+SHIFT+S):
This button inserts a template, with for instance, a time stamp and the developer's initials, as a comment before the currently selected line in the code window. It is ideal for a quick comment when maintaining your code. If more than one line is selected a time stamp template is inserted before and after the block.

Uses the boilerplates TIMESTAMP.tld, TIMESTAMP_START.tld, and TIMESTAMP_END.tld as appropriate. The boilerplates are stored in a directory as defined by the user with the configuration utility.

  Insert Code Template (Hot key: CTRL+SHIFT+T):
This combo box will insert any user-defined text file at the current insertion point in the code window. For example, it is ideal for adding standard interface definitions. The templates are stored in a directory as defined by the user with the configuration utility and end in the file type suffix .tlt (e.g. PRIVATE_SUB.tlt).

When activated with the hot key (CTRL+SHIFT+T) or by selecting from the menu, a form is displayed for you to select a template for insertion. Simply select the template and click on OK.

To save space on the toolbar, or to allow the viewing of longer file names, you can resize the templates combo box. In the IDE choose View | Toolbars | Customize and then use the mouse to resize the templates combo box. When the add-in is unloaded (this happens automatically when the VB IDE is shut down) the size of the combo box is remembered for the next time.

  Close Windows (Hot key: CTRL+SHIFT+F4):
This button closes all the code and designer windows that are currently open in the Visual Basic IDE. It is ideal for quickly tidying up the environment, especially after debugging.

  Clear Immediate Window (Hot key: CTRL+SHIFT+BACKSPACE):
This button clears the contents of the immediate window with a single click.

      Insert Error Handler 1, 2 or Error Handle all Procedures (Hot key: CTRL+ALT+F1, CTRL+ALT+F2 and CTRL+ALT+H):
There are three buttons available for inserting standard error handling. Error handling is often implemented by raising the errors up the call stack and then displaying a message at the top level if the error has not been handled. This will often mean inserting code at the top of the procedure to declare variables and start an 'ON ERROR', and code at the bottom of the procedure to handle the errors. In a single click, these buttons insert all the code, as defined by the user in template files. You can set which error handler is inserted when error handling all procedures by running the configuration utility.

When inserting an error handler in all procedures, any procedure found with an existing 'On Error' statement of some kind will be ignored and a line will be inserted in the Debug window to advise you that it was ignored.

Uses the boilerplates ERROR1_START.tld, ERROR1_END.tld, ERROR2_START.tld, and ERROR2_END.tld as appropriate. The boilerplates are stored in a directory as defined by the user with the configuration utility.

   Clean Variables (Hot key: CTRL+SHIFT+V and CTRL+ALT+V):
You can use the Clean Variables functions to remove the declaration for all unused variables from either the selected procedure or all procedures within the module. The declaration is not actually removed, it is commented out instead.

   Smart Indent (Hot key: CTRL+SHIFT+I and CTRL+ALT+I):
The smart indent function can be used to re-indent a procedure or all procedures in a module. This is particularly useful where you have imported some example code from the web and the indentation is incorrect.

  Smart Tab Order (Hot key: CTRL+ALT+T):
The smart tab order function can be used to quickly sort out the tab order for all controls in the current designer window. When this function is selected a dockable form will be displayed of all the controls in the designer window in their current tab order. Controls can then be moved either by dragging and dropping individual control names, or by using the up and down arrow keys to move one or more control names.

There are also auto-sort buttons that will sort the controls automatically either across and then down, or down and then across. The sorting is influenced by the 'Group by container' checkbox. When the checkbox is checked the controls will be kept together based on their containers (e.g. Frame, PictureBox, Tab Dialog), this is especially useful where containers overlap, for instance where you intend to show and hide frames at runtime. However, should you be using the containers simply as a visual border and want the controls sorted according to their top and left properties regardless of container then you can uncheck the box.

NOTE: The tab order is not changed on the designer window until the 'Apply this tab order' button (resembling a check mark) is selected. You can click on the refresh button at any time to redisplay the controls in the current tab order.

  ZOrder Management (Hot key: CTRL+SHIFT+Z):
The ZOrder Management function can be used to quickly bring controls on a designer window to the front of the ZOrder or send them to the back. When the function is selected a dockable window will be displayed of all the controls in the designer window in alphabetical order. A controls ZOrder can then be changed by selecting the control name and clicking on the appropriate button.

This function is particularly useful when a form is being built with overlapping frames or buttons that are shown/hidden at runtime.

  Project Statistics (Hot key: CTRL+ALT+S):
The Project Statistics function will analyse all projects in the currently opened project/project group and produce statistics for each component and a summary for each project. The data reported for each component is as follows:

  • Component Type
  • Lines of Code
  • Comment Lines
  • Blank Lines
  • Total Lines (sum of Code, Comment and Blank Lines)
  • Number of VB Controls
  • Number of Procedures

The statistics are displayed in a dockable window, if you click on the copy button at the top of the window the tab delimited statistics are put in the Windows clipboard and can then be pasted into a suitable product for further analysis (e.g. Microsoft Excel).

   Tidy White Space (Hot key: CTRL+SHIFT+W and CTRL+ALT+W):
The tidy white space function can be used to remove any redundant white space from a module or all modules. You define the number of lines of white space that are acceptable using the configuration tool, this function will then reduce any blocks of white space larger than the specified value, and any white space at the end of the module.

  Procedure List (Hot key: CTRL+ALT+L):
The procedure list function displays a list of all the procedures in the current module in a window within the IDE similar to the following:

The list is initially sorted in the same order that the procedures appear within the module and also details whether each procedure has an error handler or whether it is documented. The rules it uses are; if the procedure contains the string ‘On Error’ it is considered to have an error handler, and if the line before the procedure declaration is a comment it is considered to be documented.

The procedures within the list can be re-ordered as required using the up and down buttons, drag and drop with the mouse, or the quick alphabetical sort button. In order to apply the changed order you must click on the ‘check’ button. WARNING: Very long modules can take some time to reorganize and is dependant on the speed of your PC. We recommend that you save your code before reorganizing the procedures.

The list is not updated with any changes you make in the code window (new, changed or removed windows) until the refresh button, sort button or apply changes button is selected. Should new procedures have been added when the apply changes button is selected, the new procedures will be displayed at the top of the module after the module declaration section.

Standard Token List:
Application defined tokens used in VBCodeHelper:

%PROJECTNAME% Project's name
%PROJECTDESCRIPTION% Project's description
%MODULE% Module's name
%FILENAME% Module's file name
%AUTHOR% Author's name (as setup by the user with the configuration utility)
%CREATED% Module file's creation date (in a format as setup by the user with the configuration utility)
%COMPANYNAME% Company's name (as setup by the user with the configuration utility)
%YEAR% Current year
%DATE% Current date (in a format as setup by the user with the configuration utility)
%PROCNAME% Procedure's name
%PROCTYPE% Procedure's type (replaced as appropriate by SUB, FUNCTION, PROPERTY GET, PROPERTY LET, or PROPERTY SET)
%SCOPE% Procedure’s scope (replaced as appropriate by PUBLIC, PRIVATE or FRIEND)
%PROCTYPEMAIN% Procedure’s main type (replaced as appropriate by Sub, Function or Property)
%PROPERTYTYPE% Property procedure’s type (replaced as appropriate by (GET), (LET), or (SET)
%PARAMS% Procedure’s parameter details (only replaced when documenting a procedure with a boilerplate using the ‘Document Entire Module’ or ‘Document Procedure’ buttons)
%RETVAL% Function’s return value details (only replaced when documenting a procedure with a boilerplate using the ‘Document Entire Module’ or ‘Document Procedure’ buttons)
%TIMESTAMP% Current date and time (in a format setup by the user with the configuration utility)
%INITIALS% Author’s initials (as setup by the user with the configuration utility)
%MAJORVER% The Major Version number as read from the VB project file. As this number is read from the project file the number inserted will be incorrect if you have not saved the project since changing it. If the project file does not yet exist or cannot be found, then the value defaults to "1". This would normally be inserted into a template with the minor and revision version tokens in a format like this: %MAJORVER%.%MINORVER%.%REVISIONVER%
%MINORVER% The Minor Version number as read from the VB project file. As this number is read from the project file the number inserted will be incorrect if you have not saved the project since changing it. If the project file does not yet exist or cannot be found, then the value defaults to "0". This would normally be inserted into a template with the major and revision version tokens in a format like this: %MAJORVER%.%MINORVER%.%REVISIONVER%
%REVISIONVER% The Revision Version number as read from the VB project file. As this number is read from the project file the number inserted will be incorrect if you have not saved the project since changing it. If the project file does not yet exist or cannot be found, then the value defaults to "0". This would normally be inserted into a template with the major and minor version tokens in a format like this: %MAJORVER%.%MINORVER%.%REVISIONVER%

User Defined Tokens:
The user may define their own tokens to be used in the templates and boilerplates. This is done by editing the USER_TOKENS.dat file stored a directory as defined by the user using the configuration utility.

The user tokens file will contain one line for each token and may contain comments that are indicated with an apostrophe. Each line defining a user token contains three parts; the token name that is enclose in % characters (e.g. %DEPT%), a prompt to be displayed for a value to replace the token with, and a default value for the token. The three parts are separated with semi-colon (;) characters. If no prompt is defined the tokens will simply be replaced with the default value provided, and should no default value be provided then a prompt will be displayed with no default.

e.g. %DEPT%;Please enter the department name;IT Department


Configuration Tool:


The configuration tool is used to configure different aspects of the VBCodeHelper add-in. It consists of six pages which may be selected by using the push buttons at the top of the form.

This configuration tool can be run either standalone from the Windows Start menu, or from within Visual Basic when the add-in is running by selecting the Configure VBCodeHelper option on the VBCodeHelper menu.

On the first page you can change the location of where the add-in looks for its templates, boilerplates and USER_TOKENS.dat. However, should you change the location you will have to move the files manually yourself.

On the second page you can set the various system tokens.

The third page is used to set error handling and smart indenting options. The 'Normal Error Handler' specifies which of the two error handlers are inserted for most procedures. The 'Error Handler if Procedure name Contains Underscore (_)' specifies which error handler is used when the procedure name contains an underscore (i.e. usually an event procedure). The 'Add Error Handlers to Property Procedures' allows you to prevent insertion in all property procedures which can often be one line procedures unlikely to produce an error. The 'Number of Spaces For Each Indent' allows you to configure the indentation used for each level of indenting when the Smart Indent function is used. The ‘Indent Declaration Statements (Dim, Static, Const)’ allows you to specify whether you want the declarations up against the left margin or indented like the rest of the code. The ‘Number of Consecutive Lines of White Space Allowed’ allows you to specify the maximum number of blank lines that can appear together. The ‘Add Documentation Before or After Procedure Declaration’ option allows you to specify whether procedure boilerplates should be added before or after the procedures declaration line(s).

The fourth page is used to configure the toolbar; whether it is visible and which of the buttons are visible.

The fifth page is used to setup whether shortcuts, such as Ctrl+Shift+M for Insert Module, are enabled. It is recommended that all shortcuts are left enabled unless you have another Add-In product that conflicts with the VBCodeHelper key assignments.

The sixth and final page gives information about the software and who it is registered to.


Register Licence:


You can register the application from within the configuration tool by clicking on the Register Licence button. When the evaluation licence has expired, running the configuration tool will launch this window automatically.


Installation:

If the software has been supplied on CD-ROM it can be installed by simply inserting the CD-ROM in the PC, should the setup program not automatically start then browse the CD-ROMs contents and run the file called SETUP.EXE.

If the software has been downloaded from the internet it can be installed by running the download file called SETUP.EXE.

Simply follow all the on-screen prompts displayed by the installation program to complete the installation. Please note that you are required to accept the End User Licence Agreement before the installation will complete.

After installation of the Add-In it is recommended that you run the configuration utility that you will find in the windows Start menu under the VBCodeHelper group. Please note that should you want to store the templates, boilerplates and user tokens file somewhere other than the default folder (which is a sub-folder called Templates in the installation folder, usually C:/Program Files/VBCodeHelper/Templates), then you will have to move the files yourself and then use the configuration utility to select the new folder(s). For instance, it is quite usual to store the boilerplate files on the network somewhere so that all developers use the same standards, whilst keeping the template files and user tokens file in a local directory.


FAQ's:

Q: How can I change the error handling code that is inserted so it reflects my own style?
A: The error handling code is template driven. Simply find out where your 'boilerplate' directory is located by starting the VBCodeHelper Configuration tool. Go to that directory and edit the files ERROR1_START.tld, ERROR1_END.tld, ERROR2_START.tld and ERROR2_END.tld to reflect your own style.

Q: How can I ensure that all my developers are inserting boilerplates with the same style?
A: Get your developers to start the VBCodeHelper Configuration tool and change their 'boilerplates' directory to point to a central directory you have setup on a common file server.

Q: How can I include a version history for each procedure boilerplate?
A: The boilerplates are all template driven. Simply find out where your 'boilerplate' directory is located by starting the VBCodeHelper Configuration tool. Go to that directory and edit the files HEADER_FUNCTION.tld, HEADER_SUB.tld etc.

Q: How can I add more code templates in the VBCodeHelper combo box?
A: Simply add your files ending in a .tlt extension into the 'templates' directory as defined with the VBCodeHelper Configuration tool.

Q: I have a suggestion for an enhancement, where should I send it?
A: support@vbcodehelper.com

Q: Can I quickly remove a boilerplate entered by mistake?
A: If you have just entered the boilerplate, simply press CTRL-Z to undo the code insertion.