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 to an apostrophe. The ViviFire compiler usually ignores all comments.

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

Comments can follow a statement on the same line, or fill a full line. These are shown in the code that follows.

' This comment starts at the left edge of the screen.
Const Greeting = "Hello"  ' This comment is in-line.

If a comment is too long for one line, use the comment symbol on each line. An example follows:

' This comment is too long to keep it all on one line, thus it
' is necessary to break it into two.

A comment can follow a line-continuation sequence on the same line. But you cannot use a line-continuation sequence to continue a comment, because comments ignore all such sequences.

Because the apostrophe can show almost the same as a quotation mark, some comments can cause warnings. ViviFire shows a warning if an apostrophe follows one of these line-continuation sequences: an assignment operator, a comma, a left parenthesis, or a left brace. There are two possible corrections: (1) put an underscore symbol (_) before the apostrophe, or (2) change the comment symbol to two slashes (//).

The example that follows shows some conditions in which comments can cause warnings.

' This comment has no problem.
Function ConcatenatedFour(    ' This comment causes a warning.
      parameter1 As String,   // This comment has no problem.
      parameter2 As String,   ' This comment causes a warning.
      parameter3 As String, _ ' This comment has no problem.
      parameter4 As String) As String
    ConcatenatedFour = ' This comment causes a warning.
      parameter1 + parameter2 + parameter3 + parameter4
End Function

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.