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.
// 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.