                    Nantucket Code Guidelines

The following guidelines are applicable to all source code,
whether supplied as printed material or as a disk.



1    Commands and Keywords

1.1  All commands and keywords are uppercase, both in programs
and in text.  Be sure to specify the complete spelling; never use
the four-letter abbreviation:

     REPLACE CustName WITH cCustName

1.2  When specifying a command in text or in a special element
other than code, and the command includes a clause, separate each
keyword with an ellipsis (...) and do not specify the TO clause
unless it is followed by the FILE, PRINT or SCREEN keywords:

     COPY...SDF
     SET MESSAGE...CENTER
     @...SAY...GET



2    Language Syntax

2.1  When specifying the complete syntax of a language element in
text, input items, parameters, etc. are referred to using the
following symbols:

SYMBOLS   DESCRIPTION

< >       Indicates user input item
( )       Indicates function argument list
[ ]       Indicates optional item or list
{ }       Indicates code block or literal array
| |       Indicates code block argument list
-->       Indicates function return value
...       Repeated elements if followed by a symbol
          Intervening code if followed by a keyword
,         List item separator
|         Indicates two or more mutually exclusive options
@         Indicates that an item must be passed by reference
*         Indicates a compatibility command or function


For example:
     
     LEN(<cString>|<aTarget>) --> nCount

For more examples, please consult the Clipper 5.0 Reference
Guide.


2.2  Metasymbols describe the general nature of basic syntax
elements.  They are used in conjunction with the symbols listed
above to specify the syntax of a language element.  A metasymbol
consists of one or more lowercase data type designators, followed
by a mixedcase description:

     RANGE <dnLower>, <dnUpper>

In this example, dnLower and dnUpper can be either date or
numeric.  Data type designators are as follows:

DESIGNATOR     DESCRIPTION

a              Array
b              Code block
c              Character expression
d              Date expression
exp            Expression of any type
id             Literal identifier
l              Logical expression
m              Memo field
n              Numeric expression
o              Object
x              Extended expression



3    Filenames

3.1  The names of Clipper program and data files have the first
letter capitalized and the extensions in lowercase (e.g.,
MyProg.prg, Items.dbf).  Extensions are:

.ch       .dbt      .frm      .mem      .ntx      .prg
.dbf      .fmt      .lbl      .ndx      .txt      .vew

When referring to specific file types in text, enclose the file
extension in parentheses:

     A program is stored in a text file with a (.prg) extension.

3.2  Underscores should not be used anywhere in the filename. 
Use mixedcase for filenames consisting of more than one word:

     USE CustNames

3.3  The names and extensions of other files, including
executable and DOS files, are uppercase (e.g., CLIPPER.LIB,
AUTOEXEC.BAT).  Extensions are:

.ASM      .C        .CLP      .LIB      .OBJ      .PLL
.BAT      .COM      .EXE      .LNK      .OVL      

When referring to specific file types in text, use the
appropriate extension, including the period:

     Clipper compiles a set of (.prg) files into one .OBJ file.

3.4  Alias names follow the same conventions as filenames.



4    Fieldnames

4.1  Capitalize the first letter of fieldnames:

     @ 10,10 SAY Branch

4.2  Do not use leading underscores: these are used for Clipper
internal variable and function names.  Underscores should not be
used anywhere in the fieldname.  Use mixedcase for fieldnames
consisting of more than one word:

     ? TotalSum, NumOfLines

4.3  Always explicitly reference fieldnames, either by using the
FIELD declaration or by preceding the fieldname with the file
alias:

     FIELD CustName      OR   @ 10,10 SAY CustFile->CustName
     @ 10,10 SAY CustName



5    Memory Variables

5.1  Memory variable names consist of a lowercase data type
designator (see section 2), followed by a mixedcase description:

     cString := "Hello world"

5.2  Underscores should not be used anywhere in a memory variable
name.  Use mixedcase for names consisting of more than one word:

     nTotalCost := Invoices->Cost

5.3  Never give memory variables the same names as database
fields.



6    Functions and Procedures

6.1  Clipper function names are uppercase, followed by
parentheses:

     You can create user-friendly menus with ACHOICE().

6.2  User-defined function and procedure names begin with an
uppercase letter, followed by lowercase letters as appropriate:

     ? Center("Please select a menu option", 80)

6.3  Do not use leading underscores: these are used for Clipper
internal variable and function names.  Underscores should not be
used anywhere in a function or procedure name.  Use mixedcase for
names consisting of more than one word:

     YesOrNo("Do you wish to continue?", 10, 10)

6.4  The RETURN statement at the end of a function or procedure
is indented 1 tab (see example in section 15).

6.5  If a subroutine does not return a value, it should be
declared as a PROCEDURE.  A routine that returns a value should
be declared as a function.  (Note that calls to both functions
and procedures can occur in the middle of a line with arguments
listed in parentheses.)

6.6  The return value of a function is enclosed in parentheses:

     RETURN (cRetValue)

6.7  Wherever possible, variables referenced by a function or
procedure should be passed as parameters.



7    Preprocessor Directives

7.1  Preprocessor directives are lowercase and are preceded by a
"#" sign:

     #include "Inkey.ch"

7.2  Pseudo-function names follow the same conventions as
user-defined function and procedure names (see section 6).

7.3  Manifest constants are uppercase:

     #define ESCAPE 27
     IF LASTKEY() == ESCAPE



8    Standard Classes

8.1  Class names follow the same conventions as user-defined
function and procedure names (see section 6).

8.2  Instance variable names begin with a lowercase letter, and
include uppercase letters wherever necessary to indicate new
words:

     oError:canDefault := .T.

8.3  Method names follow the same convention as instance variable
names (see above):

     oBrowse:pageUp()

8.4  When referring to a class method in text, you must also
specify the class name:

     To reposition the data source to bottom-of-file, use the 
     TBrowse:goBottom() method.



9    Spaces

9.1  Whenever a list of two or more items is used, a space is
placed after each comma separator:

     MyFunc(nChoice, 10, 20, .T.)

9.2  If parentheses are placed around an item and the item itself
is already enclosed in parentheses, a space is placed immediately
inside the outermost pair:

     DoCalc( (nItem > nTotal) )
     cNewStr := IF( EMPTY(cStr), cNewStr, cStr + CHR(13) )

9.3  NEVER use spaces to indent code; use tabs instead (see
section 15).



10   Declarations

10.1 Each variable is declared separately on its own line:

     LOCAL nSomeNum
     LOCAL cString := ""



11   Logicals

11.1 Logical values are referred to in text as follows:

     true (.T.)
     false (.F.)

The terms "true" and "false" are all lowercase unless they appear
at the beginning of a sentence, and are followed by the code form
of the logical value enclosed in parentheses.



12   Operators

12.1 The in-line assignment operator (:=) is used for assignments
in all Clipper 5.0 code:

     lContinue := .T.

12.2 The == operator is used for equality tests in all Clipper
5.0 code:

     lDuplicate := (CustFile->CustName == cCustName)



13   Tabs

13.1 Tab size is fixed at 3 spaces.  Do not use variable tab
stops to align in-line comments.



14   Missing Code

14.1 The fact that code is missing from an example is indicated
by a line containing a period, followed by a line containing a
period and "<statements>," followed by a line containing a
period.  The lines are indented as though they contained code
(see section 15):

     IF nNumber == 0
        .
        . <statements>
        .
     ENDIF



15   Indentation

15.1 Tabs are used for all indentation. DO NOT uses spaces: it
makes layout extremely difficult.

15.2 Control structures and the code within functions and
procedures are indented 1 tab.  The same is true of a function or
procedure's RETURN statement.  Clipper control structures include
BEGIN SEQUENCE...END, DO CASE...ENDCASE, DO WHILE...ENDDO, EXIT,
LOOP, FOR...NEXT, and IF...ENDIF:

     PROCEDURE SaySomething
        DO WHILE .T.
           IF nTotal< 50
              ? "Less than 50"
           ELSEIF nTotal == 50
              ? "Equal to 50"
           ELSE
              ? "Greater than 50""
           ENDIF
        ENDDO
        RETURN

15.3 CASE statements in a DO CASE...ENDCASE structure are aligned
with the "DO CASE:"

     DO CASE
     CASE nChoice == 1
     .
     . <statements>
     .
     ENDCASE



16   Line Continuation

16.1 When a line of code reaches column 60 (or at the previous
logical break), interrupt the code with a semicolon and continue
on the next line.  Indent the line to indicate a continuation:

     SET FILTER TO CustFile->Name == "Jim Bowie";
        .AND. CustFile->State == "CA"

16.2 To continue a character string, end the first line with a
quotation mark and place the remainder on the next line.  Indent
the line to indicate a continuation:

     @ 10,10 SAY "The lazy brown fox tripped over" + ;
          "the broken branch."



17   Comments

17.1 Comments begin with a capital letter, but have no period:

     //   Just like a sentence, but no period

17.2 For long comments spanning several lines, use the following:

     * For Summer '87 code, put one of these at the start of each
     * line

     /* This type of Clipper 5.0 comment can be as large as 
     necessary.  Everything bound between the delimiters will be 
     ignored by the preprocessor
     */

17.3 For single-line comments, use the following:

     //   This is a single-line comment in Clipper 5.0

     *    This is  a single-line comment in Summer '87

17.4 For in-line comments, use the following:

     SELECT 1            &&   An in-line comment in Summer '87
     USE Customer   //   An in-line comment in Clipper 5.0

Note that consecutive in-line comments are aligned with tabs.




