Datasheet

Chapter 1: A Quick Introduction to Programming

Use Comments to Make Your Code More Clear

and Readable, but Don’t Overuse Them

When writing code, strive to make it as self-documenting as possible. You can do this by following the

guidelines set out earlier. However, self-documenting code is hard to achieve and no one is capable of

100% self-documenting code. Everyone writes code that can benefit from a few little scribbles to serve as

reminders in the margins. The coding equivalents of these scribbles are comments. But how can you tell

a good comment from a bad comment?

Generally speaking, a good comment operates at the level of intent. A good comment answers the questions:

❑ Where does this code block fit in with the overall script?

❑ Why did the programmer write this code?

The answers to these questions fill in the blanks that can never be filled by even the best, most pedantic

self-documenting code. Good comments are also generally “paragraph-level” comments. Your code

should be clear enough that you do not need a comment for each and every line of code it contains, but a

comment that quickly and clearly describes the purpose for a block of code allows a reader to scan

through the comments rather than reading every line of code. The idea is to keep the person who might

be reading your code from having to pore over every line to try and figure out why the code exists.

Commenting every line (as you probably noticed with the earlier examples) makes the code hard to

follow and breaks up the flow too much.

Bad comments are generally redundant comments, meaning they repeat what the code itself already tells

you. Try to make your code as clear as possible so that you don’t need to repeat yourself with comments.

Redundant comments tend to add clutter and do more harm than good. Reading the code tells you the

how; reading the comments should tell you the why.

Finally, it’s a good idea to get into the habit of adding “tombstone” or “flower box” comments at the top

of each script file, module, class, and procedure. These comments typically describe the purpose of the

code, the date it was written, the original author, and a log of modifications.

‘ Kathie Kingsley-Hughes

‘ 22 Feb 2007

‘ This script prompts the user for his or her name.

‘ It incorporates various greetings depending on input by the user.

‘

‘ Added alternative greeting

‘ Changed variable names to make them more readable

Summary

In this chapter you took a really fast-paced journey through the basics of programming. The authors

tried to distill a whole subject (at least a book) into one chapter. You covered an awful lot of ground but

also skimmed over or totally passed by a lot of stuff. However, the information in this chapter gave you

the basics you need to get started programming with VBScript and the knowledge and confidence

you need to talk about programming with other programmers in a language they understand.

c01.indd 29c01.indd 29 8/27/07 7:45:28 PM8/27/07 7:45:28 PM