How to naming

This document defines the naming conventions to use when performing standard or specific development tasks to avoid naming conflicts. Some of the rules stated below are classified as strict recommendations and must be followed rigorously. Others are suggestions that will be validated later.

Strict recommendations

Naming rules for dictionary elements

The code that identifies a dictionary element must follow these naming rules. This includes the following elements:

• Table name and corresponding abbreviations, as well as views and corresponding abbreviations
• Class names and corresponding abbreviations
• Collection names
• Constant names
• Method and operation names
• Representation names, corresponding abbreviations, and instance name for the associated class
• Data types
• Activity codes
• Context variables
• Parameter names and groups
• Script names (with some exceptions, see above)
• Screen, windows, objects, inquiries, and so forth, for the version 6 code

For these elements, the applicable rules are as follows:

Note: By default, when using the meta data generation tool, the collection is called according to the pattern L* (previously C*). It is not recommended to keep this style of collection name because it is difficult, and therefore, makes the code less readable. It is recommended to rename a collection by giving it a clear and explicit name that does not conflict with other properties.

Naming rules for classes and representations

These rules are in addition to Naming rules for dictionary elements. They are applicable for standard development.

Persistent classes

The main class that manages a table must have the exact same name as the table itself.

The cache class of a table must be named with the table abbreviation.

The desktop representation of a class must be named with the class name.

The mobile representation of a class must be named with the class name + the 'M' letter.

The tablet representation of a class must be named with the class name + the 'T' letter.

If an additional representation is added to the class, it must be named with the table name + a suffix that identifies its purpose.

If a variant class is added to the table, it must be named with the table name + a suffix that identifies the variant.

Other classes

Classes that are not linked to a table must be named with a name that is different from an existing table name or table abbreviation. This means the class name cannot be one that already exists in the dictionary table.

Naming rules for methods

It is important to distinguish between public methods that can be used by any developer using a class delivered in the standard, and private methods that are defined for internal use of the class implementation.

The private methods need to be prefixed by an underscore followed by a character that corresponds to the naming rule previously defined. For example:

• A method starting with "_A" is a private supervisor method.
• A method starting with "A" is a public supervisor method.
• A method starting with "_B", "_C"..."_V" is a private standard application method.
• A method starting with "B", "C"..."V" is a public standard application method.
• A method starting with "_X", "_Y", "_Z" is a private non standard method.
• A method starting with "X", "Y", "Z" is a public non standard method.

The private methods are not documented and are subject to change without notice. To avoid their use by developers that don't follow the rules, it is recommended to implement the corresponding code in a separate script that is not supplied in the source.

Numbering rules for elements identified by a number (local menus, miscellaneous tables...)

Other recommendations

Scripts organization

There is no strict recommendation about the script organization except for the following rules:

Library script

A script storing a library of functions must follow the naming rules previously defined (prefix).

When functions are written for native version 7 functions, it is strongly recommended to write them in scripts that don't contain version 6 code. This will help in the future to deprecate the version 6 code.

We need to distinguish the scripts containing version 7 native code from the scripts containing version 6 code. We considered a recommendation to add _SYRA to the end of the script name, but this might be awkward, and maybe we can find a better recommendation, such as, LIB_ means library, xxxx is an additional significant name. Further discussion is needed.

If we consider the TRTDEV V6 script that contains miscellaneous scripts related to currency controls
(currency is spelled "devise" in French), the recommendation is to have a name that contains CUR (LIBCUR_SYRA,
or CLIB_CUR, if we consider that C might be the abbreviation of core). Of course, this script will only contain code that is version 7 compliant. 

If there is a subprogram that controls the currency, it would also be nice to rename it from "CONTDEV"
to "CONTCUR."

Normalization of functions called in a library

A good practice is to avoid Subprog when creating functions in libraries, and to use Funprog instead to simplify error handling. In a case where this is not relevant, we don't have an error class that would handle the error in a simple way. So then the normalization is:

• To return [V]CST_ATRUE if the Funprog is successful.
• To return [V]CST_AFALSE if the Funprog returns an error.
• To have an additional parameter (character string with a maximum length equal to 250, such as the AMSG data type) that returns the error message if an error was raised.

Scripts associated with classes

A script associated with a class is by default created with a name in 4 segments with an underscore between the second and third segments. This creates a name in the AB_CD format, where:

• A is the class name.
• B is an optional segment (by default, it is empty, but if several scripts are present 1,2,3... it is offered). It is therefore important to note that this segment can be any other string and should be distinguished by a dedicated codification for specific or vertical scripts.
• C is the character C if the script is related to a class, and R if the script is related to a representation.
• D is one of the following strings: STD for standard, SPE for specific, VER for vertical.

For example, a vertical developer using the prefix XVE for all his dictionary elements has a vertical script associated to the standard class BPCUSTOMER. The recommended script name would be:

• BPCUSTOMERXVE_CVER if associated to the class.
• BPCUSTOMERXVE_RVER if associated to the representation.

Splitting scripts

Because a script associated with a class could be huge for complex objects, or for a better code organization, it's useful to split this script into several subscripts.

Following the previous chapter the name will have 5 segments, what changes is the end of the name AB_CD_E

• A, B, C and D: see the previous section
• E is one of the following strings:
  • EVT for class event management
  • PRO for property event management
  • MPU for public methods and operations
  • MPR for private methods and operations
  • TYP for the data type associated with the class management
  • GAT for the class GATEWAY management (see Call between classic code and V7+ code).

For example, the main script BPCUSTOMER_CSTD will call subscripts as follow:

• BPCUSTOMER_CSTD
  • BPCUSTOMER_CSTD_EVT
  • BPCUSTOMER_CSTD_PRO
  • BPCUSTOMER_CSTD_MPU
  • BPCUSTOMER_CSTD_MPR

Caution: those subscripts have not to be defined as class scripts in the class dictionnary, they are called from the main one which act as a router.

BPCUSTOMER_CSTD_TYP and BPCUSTOMER_CSTD_GAT are not called from BPCUSTOMER_CSTD. BPCUSTOMER_CSTD_TYP will be linked to the data type in the data type dictionnary, and BPCUSTOMER_CSTD_GAT will be called by the remote call API.

Example of what could be the BPCUSTOMER_CSTD routing:

$EVENT
  Gosub EVENT From BPCUSTOMER_CSTD_EVT
Return

$PROPERTIES
  Gosub PROPERTIES From BPCUSTOMER_CSTD_PRO
Return

$METHODS
  If (left$([L]AMETHOD,1) = "_")
    Gosub METHODS From BPCUSTOMER_CSTD_MPR
  Else
    Gosub METHODS From BPCUSTOMER_CSTD_MPU
  Endif
Return

$OPERATIONS
  If (left$([L]AOPERATION,1) = "_")
    Gosub OPERATIONS From BPCUSTOMER_CSTD_MPR
  Else
    Gosub OPERATIONS From BPCUSTOMER_CSTD_MPU
  Endif
Return

Collection names

A collection is a property like any other. Using prefixes like C_ is strongly not recommended, for several reasons:

• It makes the code more difficult to read.
• C_ (like R_ and in the future maybe other x_ sequences) are close to classes and representations codification style and might therefore become confusing.

This doesn't mean that naming frequent collections is not valuable. For example, having a standard short name for addresses, or cost accounting segments can be a good idea. A simple name such as IADD (invoice addresses), OADD (order addresses), or CCE (cost accounting) can be clear enough.

Naming rules for menu items

The menu items associated to classic pages have to follow the rule given by the menu profile naming tool. The other menu items follow the naming rules we already have for the other dictionary elements, described here.