Comments in Code

All through this manual you will see examples of ViviFire code with comments. Most of these comments start with an apostrophe (') and stop at the end of the line. You can also use two slashes (//) as an alternative. The ViviFire compiler ignores all comments.

You put comments in your code to tell what other code does. And frequently they give other information.

There are two types of comments: (1) the in-line comment, shown above, and (2) the mid-line comment.

A mid-line comment uses a pair of symbols to identify the start and end, and has one symbol between them. The start is a slash-apostrophe (/') and the end is an apostrophe-slash ('/). The inner part can be a name, a number or date literal, or some sequence of characters that are a part of these symbols.

Permitted punctuation characters include ! # $ % - . / @ _. But, you cannot use other punctuation or whitespace characters.

You can write mid-line comments at many positions in a line of code. But, you cannot write two adjacent comments on one line.

Examples

// This is a full-line comment.
PrintLine "Test" ' This comment is in-line with code.
PrintLine "Hi " & name _  ' This comment ...
    & " how are you?" ' is divided in two.
Call Test 1 /'one'/, 2 /'two'/, 3 /'three'/

Conventions for comments

The list that follows gives some general instructions about what type of comment can come before a section of code. These are only recommended procedures. Do what you think is best for you and all the persons who will read your code.

• Tell what a procedure does, not how it does it.
• Make a list of each external variable, control, file, or other element to which a procedure must have access.
• Make a list of each external variable, control, or file that your code can change. Tell what effect a change has, if it is not easily known.
• Tell what each argument supplies to a procedure.
• Tell what a procedure returns.

Some more to think about:

• Try to write a comment before each important variable declaration that tells how you use it.
• Try to give good names to variables, controls, and procedures. Good names can make some comments shorter or not as necessary.
• Write comments the same as sentences. start with an upper-case letter, and put a period (or other applicable punctuation) at the end.