Formatting Comments

Microsoft® Windows® 2000 Scripting Guide

In many scripting books, comments are set off from the rest of the text by use of a frame (typically a box drawn with asterisks). These frames make it easy to identify the comments; however, the frames themselves can be difficult to maintain. For example, consider the frame used to surround the comments in this script snippet:

'***************************************************************************
'*   This is a comment enclosed within a frame. These frames might look    *
'*   nice, but they can be difficult to maintain.                          *
'***************************************************************************

Although the frame might have a certain aesthetic appeal, if you edit the comment, the line lengths will change and the frame might look like this:

'***************************************************************************
'*   This is a comment enclosed within a frame. Frames might look    *
'*   nice, but they are difficult to maintain.                          *
'***************************************************************************

If you like the idea of clearly delineating comments, you might want to use only a top and bottom border instead of a complete frame, as shown in the following snippet. The comments are still easy to identify, but the frame requires less maintenance.

'**************************************************************************
'*   If you feel the need to include a frame of some kind, just use a
'*   border on the top and bottom. This is much easier to maintain.
'**************************************************************************