Basic Naming Conventions
The
rc shell, on which CSA is based, exports all variables and functions to the program environment, making them global to large portions of code (IMHO this is both an advantage and a nuissance, but I won't get into this discussion here). Because of this, we have the need to establish a precise naming convention for all names, also to make them as self-documenting as possible.
In the CSA name-space, a few name prefixes are either reserved for CSA or they are used internally by the
rc shell, by AWK or by other underlying utility programs. The reserved prefixes are:
- csa
- case-insensitive prefix reserved for CSA use. It SHOULD NOT be used by application programs to identify their own commands, functions and variable names.
- fn_csa
- where
csa is case-insensitive: same as
csa.
- _
- A single
underscore prefix is reserved for use by the CSA AWK function and variable names.
- fn_
- rc function definitions.
In addition to reserved prefixes there are others that, although not strictly reserved, are simply typical, or conventional, and they are:
- WWW_
- Decoded HTTP GET/POST variables.
- XML_
- XML-encoded strings (PCDATA), that can be safely included in XML files and templates.
- ISO_
- Template variables that are to be inserted in HTML response pages and forms. Such variables are derived from their unencoded versions by replacing special characters with their ISO representations (i.e. the
newline becomes
, and so on). CGI response variables SHOULD always be encoded like this, also to prevent the so called
cross-site scripting (CSS) vulnerabilities.
- URI_
- These are similar to ISO_ variables, but the escaping of special characters is done according to RFC 1378 and the resulting values are meant to be inserted in the QUERY_STRING part of Uniform Resource Indicator (URI) strings (i.e. the newline becomes
%0A, and so on).
- URP_
- These are a special version of the
URI_ variables, that are meant to be used in the PATH_INFO part of a URI. They are slightly different from their
URI_ equivalents, to account for the decoding done by the CGI interface on the PATH_INFO part of a URI.
- TNS_
- Recommended prefix for what I dubbed "This Name Space" (TNS) variables. These are global application-level variables that application programmers may use for their own Inter-Program Communications (IPC) needs.
For an application name-space not to clash with the CSA one, just make sure that your own CSA applications always use mixed-case function and command names (i.e.
someFunction,
MyCommand, and that), and either lower- or mixed-case variable names. Never define names that begin with either
csa or
CSA. In fact, casual all upper-case names (like
SOME_NAME) SHOULD be avoided altogether. If nevertheless you need them, you SHOULD prefix them with the string
CNS_ (e.g.
CNS_MYVAR), if they are to be exported to the environment, or
CNS (like
CNSMYVAR) otherwise. As already explained,
CNS is the prefix that CSA sets aside for use by application programs.
In addition to the naming conventions that we have seen so far, there are others that concern the naming of files on disk. The following few filename extensions are typical in a CSA application:
- somefile
- A generic data file, usually a TAB-delimited table.
- somefile,v
- RCS/CVS repository of
somefile.
- somefile.lock
- Advisory lock on
somefile.
Trackbacks (0) |
New trackback |
Print
|
