Appendix C Coding Convention

This appendix covers coding conventions and, like the previous appendix covering variable naming, will help us to produce code that is easily readable and understandable, minimizing errors, and speeding up the inevitable debugging process.

Constants

Constants should be clearly identifiable in any code that you write by using either capitals or a con prefix. This is done to avoid confusion with variables in the code. For example:

• TAX_RATE
• conTaxRate

Arrays

Arrays should be prefixed with the letter a or letters arr , depending on your preference or company policy, as well as adhering to the conventions already detailed earlier. By doing this all arrays in your code will be easier to find later. For example:

• astrName
• arrstrName

Procedure Naming

Another key to writing easy-to-read, easy-to-debug, and easy-to-reuse code is to give your procedures descriptive names. This makes them easier to find in the code and also allows you to keep sections of code for later use-because the descriptive name makes their purpose easier to understand. One trick to this is to start your procedure names with a verb:

• InitValues
• ReadData
• CloseWindow

Mixed case (that is, the capitalization of the first letter of each word) and consistency (using similar verbs) of use between different routines should also be used.

Indentation

The single most valuable thing that you can do to make your code more readable and easy to follow is proper indentation. This is the greatest way of enhancing clarity and adding a visual cue to the hierarchy to the script.

After a procedure declaration, opening loop statement, or conditional test, we indent by 2 (or 4) spaces, or use tabs. Similarly, closing statements follow the reverse indentation.

By doing this, you can easily follow the flow of your program, as this example demonstrates . The structure of the code contained within the For Next loop and the If End If statements are clear and easy to follow.

Sub ShowIndentation()




Dim intCount




Dim strMessage




For intCount = 1 to 5




strMessage = strMessage & " " & intCount




If strMessage = " 1 2" then




strMessage = strMessage & " -"




End If




Next




MsgBox(strMessage)




End Sub

Commenting

Comments are a must, especially when more than one person is working on a project, with functions that will be used by other team members . Even if you're in a position to write code that only you will ever see, we can guarantee you that after a few months of not dealing with it (or even just certain parts of it), you will forget what it does or how exactly it does it. This is where commenting comes in handy.

You can comment all sorts of aspects of the code. You can add many different comments to your procedures. Here are a few suggestions:

• Describing what they do
• Pre- and postconditions
• Return values

You can also comment things such as important variables (ones that are changed in the procedure or passed by reference) and other parts of your code. Not only will you then be able to remember what it does six months down the line, but another programmer will be able to easily follow your logic when they take over the maintenance of your code after your promotion.

Remember to also make use of the two different types of comments within your code:

• Tombstone: Comments that appear at the beginning of the code and are used to describe the code as a whole.
• Inline: Comments that are specific to particular lines that appear within the code.

What follows is an example of well-commented code.

' These comments here describe what the




' function does and what it is for.




' It can also contain information such as




' copyright notices and author name


Sub ShowIndentation()
 Dim intCount


Dim strMessage ' comment specific to this line


For intCount = 1 to 5
 strMessage = strMessage & " " & intCount


If strMessage = " 1 2" then ' another specific comment


strMessage = strMessage & " -"
 End If
 Next
 MsgBox(strMessage)
End Sub