 
                                                        Ŀ
 Aspect Technologies Coding Standards                                  
                                                           
 Written By: Steve Winn                                  
                                                             
                                                            
                                                TECHNOLOGIES
 January 2000                                          

 Including VBBS and VA programs

  Coding Standards 


1. Aspect Technolgies Software Development Values

   Aspect Technolgies, to my knowledge, is the only scripting organization
that has attempted to standardize the VScript language.  We feel that there
needs to be some sort of standard created for everyone.


1.1 Why Standardize?

   The benefits of all VScript programmers using the same coding standards
are incredible.  It would be so much easier to read each others' code,
without being struck by unfamiliar formatting.  Changes to others' code can
be made neater since the same style is used.  Productivity can be increased
since formatting questions will already be answered.

   I know that many people will reject the idea of changing to the standard
since they would feel that "their style is better", or "it will take too
much time to learn", or "it doesn't need to be done".

   Your style may be better, but if it is different from others', then you
will have a hard time reading their code and vice versa.  It would make
things more simple.

   It doesn't take long at all to learn, since most of the standards listed
are common sense.

   Standardizing is not that big of a deal when compared to other things,
but reading code in an unfamiliar format is like going against the grain -
you have to constantly think about what goes with what.  Reading code that
you are used to, you will not notice that there is a format - you will see
exactly what it does.


2. VScript Source Code

   The standards we adhere to are those used by Steve Winn (founder).


2.01 Block Header

   Each VScript source code file should begin in the form:

! 
!
! ORGANIZATION NAME/YOUR NAME                                    DATE
! PROGRAM NAME                                                   File 1 of x
!
! ANY IMPORTANT INFORMATION
!
! COPYRIGHT ACKNOWLEDGEMENTS
!
!  Notice 
!
! NOTICES, SUCH AS DISCLAIMERS
!
!  History 
!
! COMPLETE HISTORY INFORMATION (Only in first source file)
!
! 


2.02 '&' Statements

   The & statement is the VScript include statement.  We will refer to the
'&' statement as an include statement.  If you use any include statements in
the program, they should come right after the block header.  If you are
creating a script for AT2k, then the first statement after the block comment
should be:

         & "ASPECT.VH"

   The file "ASPECT.VH" contains all of our standard call functions, such
as the Exit_Script function.  We also include any other functions that we feel
that we will use over and over.  The header file "ASPECT.VH" can be
downloaded on our technical support BBSes.  It is necessary in order to
successfully compile any of our scripts.  You can also request it by sending
us E-mail.

   The included files do not have to be in any specific order.  Putting an
include statement in any other place is frowned upon.

-VA Note-
   The VA script language does not have an include statement. It instead uses
CALL "script" to load another script. If you are converting VBBS scripts to
VA scripts, then I recommend that you copy the needed portions of the VBBS
included script to a new file that can be converted without errors.


2.03 Upper/Lower Case

   The VScript language is not case sensitive, but all statements should be
in lower case.  Function names should be in the format where the first letter
of each word is capitalized and the rest in lower case. All constants should
be in uppercase. Ex:

   # Function_Name
   command $CONSTANT
   test $var = 0 Zero_Variable


2.04 Code Comments

   The code should be clear and understandable by the very nature of its
design and architecture.  Also, by the appropriate choice of variable and
function names it should be as self-documenting as possible.  There should be
very few actual comments in the code itself.  If there is a particular item
the reader needs to be infomed of, then a comment is allowed.  But if you add
comments because a particular portion is unclear and misunderstood, then you
should redesign that portion so it is clear.

   You may also include comments pointing out an idea for a future version. Be
sure to make it clear that the comment is not referring to the current
version to avoid misunderstanding.

-VA Note-
   The notation I use for making comments varies from the VBBS script language
to the VA script language. The VBBS scripts should be commented with a double
exclamation mark "!!", and the VA scripts would be commented with a single
apostraphe "'". If you convert your programs from VBBS to VA with a converter,
then the VA comments will be shown as "'!".

   After you have converted your program, there will be an enormous amount of
comments in the program (being the VBBS code). This will slow your VA program
down considerably. My utility RemCom will remove those comments from the
program and correct some of the language differences. Those comments that were
in the original VBBS script will be kept, since they are represented as "'!".



2.05 Variable/Function Names

   Variable and function names should be made to represent what they contain
or what it will do.  The underscore character is recommended to clearly
define them.  Words contained in the name should be separated by the
underscore, while numbers should not be, ex: '# End_Of_File' and '$option1'.
Variables that contain filenames, should not be separated by an underscore,
ex: '$datafile' or '$configfile'.

-VA Note-
   The VA variable names are nothing like the ones used in VBBS. This is the
main advantage you gain by writing in the VBBS language, and then converting
the program to VA's language. The standard for VA variable names is that it
must be in capital letters and followed by a numeric digit "A0".


2.06 Indentation

   Use the common standard of tab stops every three to five columns.  More
than this will lead to the code going past the 80th column, and less than this
makes it hard to tell, visually, which code sections line up vertically.

   Indent every if, else, do, and do while block one tab stop.  In a switch
construct, keep each 'case' statement at the same indent level as the 'switch'
statement itself, but indent the code under each case one tab stop.

   Also indent the body of an open command and return to the previous indent
level when a close statement is reached.

-VA Note-
   The indentation of the VA scripts is a little bit different. After you have
converted a VBBS to VA script, the new file will be indented either 2 to 3
spaces over. This is the method I've been using currently to eliminate some
of the rework needed to correct this.


2.07 80-Column Lines

   Source code lines that are not made up of text should never go past the
80th column.  Lines that are text in quotations may go past the 80th column
if there is not anything after it.  This will keep all commands visible when
scrolling through with a standard text editor.


2.08 Blank Lines

   Use a single blank line to separate:

   - the block comment header from the include statements
   - the include statements from the beginning of the code
   - variable assignments from the code

   You can also use blank lines to separate 'menu' or 'ef' commands from the
rest of the code.  Use blank lines sparingly to separate blocks of related
commands.

   Use two blank lines to separate new functions from what precedes it, except
when you are performing a loop or other minor functions.


2.09 Color Coding

   Use heart-coded ANSI to color transmitted data.  Never use the '$' color
commands, since they can easily be mistaken for variables, and try not to use
the 'ansic' command since it has to be on a line itself.  Only use the true
ANSI escape-code if the color you need is not included as heart-code, or if
you are including a menu in the code that requires the escape-code ANSI.


2.10 If/Else/Endif Statements

   Every 'If' statement must end in an 'Endif' statement. Ex:

   If $var = 0 then
      If $var2 = 0 then
         ...
      Endif
   Endif

   If $var3 = 1 then
      ...
   Endif

-VA Note-
   There is not a structured If, Endif system in VA. Instead you must create
a temporary label and use a GOTO statement. Here is the same example above:

   IF A0 <> 0 GOTO templabel1
   IF B0 <> 0 GOTO templabel1
      ...

   templabel1:
   IF C0 <> 1 GOTO templabel2
      ...

   templabel2:

  Technical Support 

 If you need any help or have any questions regarding VBBS/VA then contact me
 with the following ways...

      Internet E-Mail:  swinn@midwest.net
      Internet Website: http://scribers.midwest.net/swinn
      AT2k Design BBS:  telnet: at2k.dhs.org

 
