Preface

Naming Schemes

Why Prefixes?

Underscore vs. Hyphen

Hyphenation Rules

Function Prefixes

Global Variables

GET Functions: Prompt or Property Accessor?

We Use -> for Conversions

Notational Conventions

Table of Variable Name Prefixes

Naming

"It is critical to choose meaningful names for your variables and functions. Avoid short, two or three letter names unless those names are really meaningful. While you may want to use short, abbreviated names to avoid typing, this habit will make your code more difficult to read later.

While you should avoid short names, consistently using names that are too long can present problems, too. This can lead to code that must be split across multiple line because the names are too long. Even so, it is probably better to trend to overly long names than short, abbreviated names." (by permission of Bruce E. Wampler, http://www.objectcentral.com/)

Why Prefixes?

AutoLISP does not protect symbols or even functions from overwriting, and does not separate symbols in packages (separate namespaces). Therefore it's strongly recommended to protect you own symbols with prefixing them with your own so that other programs cannot delete or alter your symbols or functions.

For the stdlib we use therefore the STD- prefix, plus some others for extended versions, like GL- or DCL-.

Pro's:

1) All other unprefixed symbols are very likely to be overwritten if you use more than one AutoLISP program!

2) You can trust in the source of origin.

Of course prefixing doesn't solve the problem, other symbols could use the same prefix. Autodesk programs often use prefixes, such as m: or ai_

Common Lisp packages use the <package-name>: prefix. Packages shadow its symbol which is not possible with AutoLISP. We use the library with modules, that's why we use the hyphen as delimiter, not the double-colon.

Con's:

Every programmer prefers short names over long descriptive ones because of :

1. Laziness, they are faster to type.

2. Typing errors.

3. Lisp Formatting Guidelines force functions to be very short, typically 5 lines of code.

ad 1: With advanced lisp editors, symbols known to the IDE are automatically expanded. For AutoLISP this aera started with Vital Lisp. R15 will include this as Visual Lisp, so Ctrl-Shift-Space (symbol completion) will be used by everyone sooner or later. On Unix or 4DOS I used this feature for years, for AutoCAD symbol table names I implemented keyboard name completion from R9 on for myself. Still hoping that this will be implemented in any future release.

ad 2: see ad 1. Typing errors are easily detected, because known names are shown colored.

ad 3: Well this really a drawback. But it is always better to have descriptive self-explanatory names than short ones. It must not be heavily commented. And lisp programs are still about 10 times shorter than C or C++ programs.

Underscore vs. Hyphen

C programers are used to the "underscore" _ delimiter whilst in Lisp the "hyphen" – is used. I vote for the hyphen, though Autodesk AutoLISP sample code uses the underscore heavily. You see their background. Vital Lisp with a lisp background uses the hyphen. Anyhow, putting religion aside, one of these should be used consistently.

Historical background: C syntax disallows hyphens in symbol names because it's a delimiter, used for the minus operator. Lisp has an clear and not misinterpretable syntax, a hyphen cannot be misunderstood as a minus operator.

Hyphenation Rules

When should a hyphen be used as delimiter? For example on predicates: When to add -P or just P?

1) Functions names already containing a hyphen should add the next suffix with a hyphen.

2) Objects, methods and properties should be seperated with hyphens. Esp. Acad specific objects.

3) All hyphenation rules ignore the STD- or another module prefix. We would use std-integerp and not std-integer-p.

Examples for these rules:

STD-TBL-P, STD-PAPERSPACE-P, STD-DCLACTIVE-P, STD-CMDACTIVE-P, STD-SCRIPTACTIVE-P, STD-HATCH-P, all VL test predicates like STD-VL-P, STD-VILL-P , STD-VLA-P and such,

because they test for acad unique objects or features, no lisp specific features or types.

But not STD-FILEP, STD-REALP, STD-INTEGERP, STD-ENAMEP, STD-PICKSETP, STD-POINTP, STD-2DPOINTP, STD-3DPOINTP, STD-FLAGSETP, STD-BITSETP and such.

They are either native AutoLISP types (not AutoCAD objects) or other one-worded functional predicates. A point is a lisp structure no AutoCAD structure.

Tricky example: use string-lessp or string-less-p?

Should it test for the object string-less or should it test strings with less? Obviously the second so it should be named string-lessp

I know, this is confusing.

Function Prefixes

All StdLib functions are prefixed with STD-

Internal library functions are prefixed with std-%. They are not documented and should not be used, because they may change completely without further documentation. They are also defined lowercase whilst all documented functions are define uppercase in the sources for better readability.

Some extended libraries prefix their functions and symbols with a short character code and '-', e.g.: BINIO-, INIFILE-, REGISTRY-, DCL-, GEOM-, DWG- or GL-

Only a few functions are not prefixed with STD- and therefore not protected from accidental overwriting.

They are in particular:
stringp, consp,
x-of, y-of, z-of, xy-of,

first, second, third, ..., rest

Global Variables

Global symbols are surrounded by '*' and written in uppercase, for example

*LOAD-VERBOSE* - a global Boolean interpreted by loader functions (ANSI compliant, and used in Vital Lisp) or

*GL-TOL* - a global variable from the Graphic Library., similar to *NUM-TOL* from STDMATH.

Application dependent default values may be prefixed with your app-prefix and ":" like my:def-lengthen-dist.

These are used in one function (e.g. for default values) only.

stdlib internal global variables therefore are named: *STD:<varname>* if global over different modules or only std:<varname> if global only in the defining module, "private for this module only". (there's no way to define variables local to modules only so far)

Without the STD: prefix they are not privat to the stdlib, they can and should be shared by other libraries and applications also.

GET Functions: Prompt or Property Accessor?

For historic reasons GET functions in AutoLISP wait for user input and should therefore not be mixed with object accessors, which are in other languages usually prefixed with GET. The ActiveX interface unfortunately introduced GET and SET (named: PUT) methods. This is somewhat confusing.

For example what does getcolor do?

Does it prompt for a color name or does it retrieve the color property from an entity?

With Visual LISP and the built-in ActiveX methods, all the object accessing GET functions are prefixed with VLA-

We will use STD-GETxxx only for the standard AutoLISP GETxxx functions, overloading their behaviour. (getstring, getint, getreal, getdist, getpoint, getkword)

We will NOT introduce new STD-GETxxx functions for user input, instead we're using either STD-INP-GET or STD-TBL-GET prefixes. A shorter STD-UGET prefix was also in consideration, but INP reminds more to the STDINPUT module behind.

All new STD-GETxxx functions are reserved for object property accessors, like STD-GETLAY, STD-GETPT, STD-GETENDPT, STD-GETHANDLE and so on to be consistent with the ActiveX method naming convention.

We Use -> for Conversions

Special conversion functions which require a special argument type use "->" inside the name instead of "2" (speak "two" and mean "to". BTW: This convention arose long before Prince)

Example: std-string->list instead of std-s2l

Which follows the conventions in Common Lisp, Vital Lisp and Scheme, the "2" often appears in C-like functions and in the comp.cad.autocad AutoLISP FAQ code which code is depricated soon.

Some general conversion functions use the "to", like
(std-tostr expr) which converts any type to a string. (std-princ-to-string) is the other possibility, already used in vill and vlisp.

Notational Conventions

This is how we try to distinguish arguments, return values, user prompts, user input by fonts and font attributes:

Return values or return types are prefixed with =>

Code in Lucida Console,

Fielnames in Courier

User Prompts are in Times Roman,

User Input in Times Roman Italic

Optional arguments appear in [] (only in extensions)

Alternative arguments before and after |

Multiple arguments are specified with ellipses, like int...

Comments that are for discussion only and will not appear in the release version is in Times Roman Italic.

Table of Variable Name Prefixes:

Functions:
STD- External, documented function
STD-% Internal, undocumented function
Globals:
*<name>* Global variable which name is common, (known from other lisps) or useful for other non-stdlib applications too
*STD:name* Global variable which is private to the stdlib.
Locals:
_$a Local variable which is to be evaluated. During evaluation this name might be overridden and should therefore be protected.
_a Local variable which also occurs as lambda list parameter and therefore prevents the VL compiler from linking this symbol. To enable the linking of common arguments without the _ prefix.

For a mapping of argument names and their usual argument types see the next section: Used Abbreviations of Argument Types