( by Greg Holmes )
The general rule of thumb is: built-in features in lowercase, and custom-written functions in mixed case.
When specifying the complete syntax of a language element in documentation, the input items, parameters, and so on are referred to using the following symbols:
Metasymbols provide a place holder for syntax elements, and they describe the expected data types. A metasymbol consists of one or more lowercase data type designators followed by a mixed case description. This is known as Hungarian Notation.
In this example,
|Filenames and Aliases
All filenames, in any context, are in upper case. Filenames follow DOS naming conventions (preferably limited to letters, numbers, and the underscore).
When referring to specific file types in documentation, include the period.
Fieldnames are all uppercase, and always include the alias of the table. Fieldnames may contain underscores, but should not begin with one (because the underscore is generally used to indicate an internal symbol).
Memory variables consist of a lowercase type designator followed by a mixed case description (see Hungarian Notation). Although CA-Clipper only recognizes the first 10 characters as unique, variable names may be longer.
If you use Hungarian Notation for your memory variable names and include the table alias with fieldnames, there will be no conflict between the two.
|Commands, Functions, and Keywords
All built-in commands, functions, and keywords are lowercase. In documentation, the font should be Courier or a similar font. If fonts are not available, then bold or CAPITALIZE the word for emphasis.
Never use abbreviations — this practice is not necessary with a compiler, although it was common in the early days of dBase (which was an interpreter).
There should never be a space between the function name and the opening parenthesis. Also, note that the
When specifying commands that have clauses in documentation, separate the keywords with an ellipsis (
|Programmer-Defined Functions & Procedures
These begin with an uppercase letter, followed by mixed case letters as appropriate.
Function and procedure names may contain underscores, but should not begin with one (they may conflict with internal functions which often start with an underscore). There should be only one
The return value of a function is not enclosed in parentheses, although parentheses may be used to clarify a complex expression.
Preprocessor directives are lowercase and are preceded by the
Optionally, you may use single quotes around header files that come with CA-Clipper and double quotes around your own. This convention is purely voluntary, but it helps to distinguish between the two. For example:
Manifest constants are uppercase.
Pseudo-function names should also be uppercase.
Local variables are grouped according to functionality, and may be declared on one or more lines. The declarations appear as the first code at the beginning of a function or procedure.
Variables may be declared one per line and accompanied by a description.
The description can be omitted if better variable names are chosen.
Variables can be initialized when they are declared, although it is often clearer (and safer) to initialize them immediately before they are used.
The in-line assignment operator (
Although the compound assignment operators (
The increment (
Whenever a list of two or more items is separated by commas, the commas are followed by a space.
Spaces may be used between successive parentheses.
Spaces should surround all operators for readability.
In declarations, often spaces are not used around the assignment operator. This tends to make searching for the declaration of a variable easier.
Thus, searching for “
Indenting control structures is one of the easiest techniques, yet it improves the readability the most.
Indent control structures and the code within functions and procedures 3 spaces.
Case statements in a do…case structure are also indented 3 spaces.
Do not use tabs in source code — insert spaces instead. Tabs cause problems when printing or when moving from one editor to another, because of the lack of a standard tab width between editors and printers. Typically, printers expand tabs to 8 spaces which easily causes nested control structures to fall off the right-hand side of the page. Commonly, a source code editing program will insert the appropriate number of spaces when the <TAB> key is hit.
When a line of code approaches the 80th column, interrupt the code at an appropriate spot with a semicolon and continue on the next line. Indent the line so that it lines up in a readable manner.
To continue a character string, end the first line with a quote and a plus sign and place the remainder on the next line. Try to choose a logical place in the string to break it, either at a punctuation mark or after a space.
Use double quotes for text that needs to be translated (will appear on the screen), and single quotes for other strings.
This is a simple but extremely effective technique because translation departments often want to see the messages in context (in the source code), so the different quote types indicate which messages are to be translated and which should be left alone.
Comments are structured just like English sentences, with a capital letter at the beginning and a period at the end.
You may encounter old-style comment indicators if you maintain older (Summer’87 and earlier) code.
For in-line comments, use the double slashes.
Note that the ‘