Making proper VBA Comments

Today we will focus on VBA Comments i.e. how to make comments in VBA or disable lines of macro code. Comments are needed in any script to explain what the code is supposed to do or provide some verbatim on certain lines / blocks of code. Scripts without comments are a nightmare for many of us – making it sometimes impossible to read through the intentions of the author. If you want to make it as easy as possible for someone to reuse your code – learn how to make proper comments.

How to make comments in VBA?

VBA Comments are lines of code preceded with the comment character '. VBA supports only single-line comments. Everything after the ' character will be ignored by the Visual Basic for Applications compiler.

Alternatively, to make comments, you can utilize the Edit toolbar from the View->Toolbars menu in VBA Project.

Below a simple example of a single line VBA comment:

Dim x As Long
'This is a comment
x = 10

A multiline VBA comment:

Dim x As Long
'This is a 
'multiple line
'comment
x = 10

Little known fact: you can also create comments in VBA by preceding them with the REM keyword, although it does not make much sense to do so:

'This is a comment
Rem this is also a comment in VBA!

VBA Comments – Best practices

Making VBA comments is not hard. It is the rule of making proper comments in the right place that make a difference. Below I am list a couple best practices that I think anyone writing Visual Basic for Applications scripts should adopt.

Commenting procedures

Make sure to place comments within VBA procedures (Functions and Subs) that provide a more complex capability.

Comment the purpose of procedures (Subs and Functions) . Ideally each procedure should accomplish a single tasks and have no more lines of code than can be made visible on your screen. A procedure should also be described by:

Explaining the purpose / goal of the procedure e.g. read file
If needed, describing the parameters and outputs

A simple example below:

Function ReadFile(fileName as String, length as Long) as String
'Read a text file, and return [length] first characters
'fileName - name of the file to open
'length - number of characters to read
  '...
  '...
End Function

Comment associated blocks of code. Usually your procedure will consist of several block of code, each one realizing a different activity. Providing even a single line of comment to explain each block of code will make your code more readable.

Explain conditional statements. Conditional statements are your codes Fork to different execution pathways. If the code does not speak for itself it makes sense to provide some verbatim.

If age < 18 Then 'Can't drink or drive
  '...
ElseIf age < 21 Then 'Can drive, can't drink
  '...
Else 'Can drink and drive. But not simultaneously :)
  '...
End If

Related posts: