Naming Conventions
This document defines the naming conventions used to avoid naming conflicts when performing standard or specific development tasks. Some of the rules stated below are classified as strict recommendations and must be followed rigorously. Others are suggestions.
| Type | Recommendations |
|---|---|
| Strict | Dictionary naming |
| Strict | Class and Representation naming |
| Strict | Method naming |
| Strict | Local menu numbering |
| Suggestion | Script naming |
| Suggestion | Collection naming |
| Suggestion | Menu items naming |
Strict recommendations
Naming rules for dictionary elements
The elements listed below are all dictionary elements:
- Table names and their corresponding abbreviations, as well as views and their corresponding abbreviations
- Class names and their corresponding abbreviations
- Collection names
- Constant names
- Method and operation names
- Representation names, their corresponding abbreviations, and the instance names for the associated classes
- Data types
- Activity codes
- Context variables
- Parameter names and groups
- Script names (with some exceptions, refer to Scripts organization)
- Screens, windows, objects, inquiries, etc. (for the version 6 code)
For these elements, the applicable rules are as follows:
| Naming pattern | Use |
|---|---|
| A* | Supervisor elements. |
| B* to T*, V* | Standard elements. |
| U* | Usually reserved for temporary tables used during updates. |
| W* | Generated elements. Those are only generated by an automatic process. Modifying them manually is forbidden. |
| X* | Add-on codes that might be developed outside of Sage. |
| Y*, Z* | Specific elements developed outside of Sage. |
| QLFarea_case | Test cases for automated tests. It is good practice to group the unit tests of the same area by having a common prefix. The naming rules are:
|
Note: By default, the collection is called according to pattern L_∗ (previously C_∗) when using the metadata generation tool. It is not recommended to keep this style of collection name because it is difficult and 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 must be applied in addition to the naming rules for dictionary elements. They are applicable for standard development.
Persistent classes
- The main class that manages a table must have the 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 followed with the letter "M".
- The tablet representation of a class must be named with the class name followed with the letter "T".
- If an additional representation is added to the class, it must be named with the table name followed with a suffix that identifies its purpose.
Object Name Table MYTABLE Main class MYTABLE Cache class MYT Main desktop representation MYTABLE Main mobile representation MYTABLEM Main tablet representation MYTABLET Additional representation MYTABLEAD1 - If a variant class is added to the table, it must be named with the table name followed with a suffix that identifies the variant.
Object Name Table MYTABLE Main class MYTABLEVAR Main desktop representation MYTABLEVAR Main mobile representation MYTABLEVARM Main tablet representation MYTABLEVART Additional representation MYTABLEVARAD1
Other classes
Classes names cannot be the same as the name or the abbreviation of an existing table if they are not linked to it. No class name can be the same as one that already exists in the dictionary table.
Naming rules for methods
Note: Public methods can be used by any developer using a class delivered in the standard. Private methods are defined for internal use of the class implementation.
Private methods need to be prefixed with an underscore, followed with a character corresponding to the naming rules 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" or "_V" is a private standard application method.
- A method starting with "B", "C" or "V" is a public standard application method.
- A method starting with "_X", "_Y" or "_Z" is a private non standard method.
- A method starting with "X", "Y" or "Z" is a public non standard method.
The private methods are not documented and are subject to changes without notice. It is recommended to implement the corresponding code in a separate script (not supplied in the source) to avoid their use by developers that do not follow the rules.
Numbering rules for elements identified by a number
| MISCELLANEOUS TABLES | |
|---|---|
| Range | Use |
| 1000-1999 | Vertical developments |
| 4000-4999 | Add-ons |
| 6000-6999 | Specific developments |
| 8000-8999 | Localizations |
| 13000-13999 | Add-ons |
| 18000-29999 | Add-ons |
| LOCAL MENUS | |
| Range | Use |
| 160-164 | Messages for specific developments |
| 165-169 | Messages for vertical developments |
| 1000-1999 | Local menus for vertical developments |
| 4000-4999 | Add-ons |
| 5100-5199 | Messages for vertical developments |
| 5100-5199 | Local menus for vertical developments |
| 5200-5999 | Local menus for vertical developments |
| 6000-6199 | Messages for specific developments |
| 6200-6999 | Local menus for specific developments |
| 8000-8999 | Localizations |
| 13000-13999 | Add-ons |
| 18000-29999 | Add-ons |
Suggestions
Scripts organization
There are no strict recommendations for script organization, except for the following rules.
Library script
A script storing a library of functions must follow the naming rules previously defined.
Caution: Do not add version 7 native functions in scripts containing version 6 code.
Normalization of functions called in a library
Try to avoid the use of subprog when creating functions in libraries. Use funprog instead to simplify error handling.
No error class can handle the error in a simple way in the case where this is not relevant. In this case, the normalization is:
- To return
[V]CST_ATRUEiffunprogis successful. - To return
[V]CST_AFALSEiffunprogreturns 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
By default, scripts associated with a class have names in four segments, with an underscore between the second and third segments. The format of the name is AB_CD, where:
- A is the class name.
- B is an optional segment. It is empty by default, but suggestions are offered if there are multiple scripts. This segment can consist in any string, and it should be distinguished by a dedicated codification for specific or vertical scripts.
- C is character "C" if the script is related to a class, or "R" if it is related to a representation.
- D is either of the following strings: "STD" for standard, "SPE" for specific, or "VER" for vertical.
Example: A vertical developer using prefix "XVE" for all his dictionary elements has a vertical script associated to 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
It can be useful to split scripts into several subscripts, either because the script would be too large, or simply for a better code organization. In this case, each subscript name should consist in five segments, with format AB_CD_E:
- A, B, C and D are as described above.
- E is either 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 (refer to Calling classic code from service code for more information)
Example: Main script "BPCUSTOMER_CSTD" will call its subscripts as follows:
- BPCUSTOMER_CSTD_EVT
- BPCUSTOMER_CSTD_PRO
- BPCUSTOMER_CSTD_MPU
- BPCUSTOMER_CSTD_MPR
Caution: These subscripts are called from the main script which acts as a router. They do not have to be defined as class scripts in the class dictionnary.
"BPCUSTOMER_CSTD_TYP" and "BPCUSTOMER_CSTD_GAT" are not called from "BPCUSTOMER_CSTD". "BPCUSTOMER_CSTD_TYP" is linked to the data type in the data type dictionnary, and "BPCUSTOMER_CSTD_GAT" is 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
Naming rules for collections
A collection is a property like any other. We strongly recommended not to use prefixes such as "C_" for several reasons:
- They make the code more difficult to read.
- "C_" (or "R_") are too close to the classes and representations codification style, which can be confusing.
However, naming frequent collections can be useful. For example, you can have a standard short name for addresses or cost accounting segments, such as "IADD" (invoice addresses), "OADD" (order addresses), or "CCE" (cost accounting).
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 same naming rules as the other dictionary elements.