Name, synonym, and comment
This article describes the standards that apply to object names, synonyms, and comments. All of the listed recommendations are mandatory unless noted otherwise.
1.1. An object Synonym must describe the object in a concise manner, which reflects the object purpose. A synonym is mandatory for each object.
This is required because synonyms are present in the user interface (in forms, reports, command interfaces, and so on), and therefore they must describe objects correctly, clearly, and consistently. Besides metadata objects, this requirement also applies to metadata object attributes, tabular sections, tabular section attributes, register dimensions, resources and any other configuration objects that have synonyms.
1.2. We recommend that you do not use abbreviations for synonyms. You can make an exception for abbreviations that are well known to the target audience (such as Sum, TIN, or SSN).
1.3. The meaning of all terms used in object synonyms must be clear to users, and the same is true for any messages displayed to users. Do not use slang, informal names of products or companies, English words written in foreign alphabet, foreign words written in English alphabet, and so on.
1.4. Specify synonyms for standard attributes of metadata objects based on their actual meaning in your application.
1.5. For standard attributes Parent and Owner, always change their default synonyms. For example, a configuration contains the Files catalog, which has a standard attribute Owner of CatalogRef.FileFolders type.
- Leave the default synonym "Owner" of the standard attribute Owner.
- Define the synonym that reflects the object meaning, such as "Folder" or "Directory".
For some catalogs it is okay to leave the default synonym "Description" of the standard Description attribute. For the Files catalog, you can choose the synonym "File name", and for the Individuals catalog you can choose the synonym "Full name".
1.6. If you have two or more similar metadata objects, ensure that their synonyms fully describe them.
Incorrect catalog synonyms:
- Bank accounts
- Counterparty bank accounts
- Company bank accounts
- Counterparty bank accounts
The names must explicitly describe the objects. Otherwise, users will ask: "If the Counterparty bank accounts catalog stores bank accounts of counterparties, whose accounts are stored in the Bank accounts catalog?"
This requirement also applies to synonyms of subordinate metadata objects (attributes, tabular sections, dimensions, resources, and so on).
The following example describes synonyms for attributes of the Items tabular section of the InventoryCount document.
- Count (from accounting)
- Count (available)
- Count (from accounting)
The following example describes synonyms for the standard Description attribute and another attribute of the Items catalog.
- Extended description
- Description for viewing
- Description for printing
2.1. We recommend that you create object Name based on its synonym (by removing spaces and other characters that are not allowed in names and capitalizing the first letter of each word). Examples:
- the AdditionalDataAndAttributeSets catalog has synonym "Additional data and attribute sets".
- the AttachedFiles command has synonym "Attached files".
You can use shorter names where one or several words of the synonym are omitted. Examples:
- ServerResponseTimeout has synonym "Server response timeout (sec)"
- NumberOfUnits has synonym "Number of measurement units"
- AttributeName has synonym "Attribute name (property)"
When creating names from synonyms, omit articles. You can also omit prepositions and conjunctions. For example, the DiscountMarkupValue attribute has synonym "Discount or markup value".
On the other hand, you can use shorter synonyms where one or several "technical" parts of the name are omitted.
This requirement ensures that configuration objects and their presentations in the user interface are easily recognizable. It helps at the deployment stage because developers usually do not participate in this process, leaving it to deployment specialists.
See also: Metadata object names in configurations
2.2. Metadata objects with Delete prefix are an exception to this rule.
Also, do not rename metadata objects, their attributes, forms, and so on if the objects must comply with backward compatibility requirements. In particular, different library versions within a single revision must be compatible with each other.
2.3. Names of top-level metadata objects (catalogs, documents, and so on) must not exceed 128 characters.
2.4. We recommend that names of subordinate metadata objects (attributes, dimensions, resources, and so on) are not identical to parent object names. For example, the User dimension (that has CatalogRef.Users type) of the TaskExecutors information register has incorrect name; it should be named Executor to reflect its meaning.
2.5. We recommend that you do not use names identical to query language table names (Document, Catalog, InformationRegister, and so on). Such names can cause errors during query execution, cumber the use of query builder and decrease the clarity or query text. For example, this query returns an error:
InformationRegister.Information AS Information
3.1. Specify the Comment only when you need to leave a note on the object for another developer. Example comments to a catalog attribute are "Indexing is implemented for optimization of reports filtered by counterparty" and "Used in foreign currency accounting".
3.2. Start your comment with a capital letter. Use periods only in abbreviations.