Scope: managed applications, mobile applications, and ordinary applications.
1.1. Make sure your object synonyms concisely state object purposes. It is required for every object.
As synonyms are displayed in the user interface in forms, reports, command interfaces, and so on, they must correctly and equally identify their entities. Besides metadata objects, this requirement applies to metadata object attributes, tabular sections, tabular section attributes, register dimensions, resources, and other configuration objects that have synonyms.
1.2. We recommend that you do not use abbreviations for synonyms. Exceptions are widely used abbreviations, such as VAT or IFRS.
1.3. Use commonly used terms in object synonyms and messages displayed to users. Do not use slang, informal names of products or companies, and so on.
$$$
Incorrect: "Import data from Excel", "Import data from MS Excel".
Correct example: "Import data from Microsoft Excel".
1.4. If metadata objects have standard attributes or standard tabular sections, specify synonyms for them on the basis of each attribute purpose.
1.5. For standard attributes Parent and Owner, always set synonyms different from their default synonyms. For example, a configuration contains the Files catalog with the Owner standard attribute of the CatalogRef.FilesFolders type.
Do not use
- The default synonym Owner of the Owner standard attribute.
Correct example:
- Make sure the synonym reflects its purpose: "Folder" or "File directory".
Another example. The Description default synonym might be suitable for the Description standard attribute of some catalogs. In other cases, you might want not to use the default synonyms. For example, for the Files catalog, you can set "File name" synonym, and for the Individuals catalog you can set "Full name" synonym.
See also: User object presentations, Texts
1.6. If you have two or more metadata objects with similar purpose, make sure their synonyms fully describe them.
Incorrect catalog synonyms:
- Bank accounts
- Counterparty bank accounts
Correct example:
- Company bank accounts
- Counterparty bank accounts
The object names must be explicit. 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, such as attributes, tabular sections, dimensions, resources, and so on.
Have a look at the following example with attributes of the Goods tabular section of the Inventory count document.
Incorrect example:
- Quantity
- Quantity (recorded)
Correct example:
- Quantity (in stock)
- Quantity (recorded)
Have a look at the following example with the Description standard attribute and another attribute of the Products catalog.
Incorrect example:
- Description
- Full description
Correct example:
- Internal description
- Label description
2.1. Use synonyms to create object names. Remove spaces and other incorrect characters and capitalize the first letter of each word.
Incorrect:
- "Additional properties" synonym is set for the AdditionalAttributesAndInfoSets catalog.
- "Files attached" synonym is set for the AttachedFiles command.
Correct example:
- "Sets of additional attributes and information records" synonym is set for the AdditionalAttributesAndInfoSets catalog.
- "Attached files" synonym is set for the AttachedFiles command.
Names can also be shorter than synonyms. You can abbreviate insignificant words from synonyms in names. For example:
- ServerTimeout has "Server timeout (sec)" synonym.
- UnitsCount has "Number of units of measure" synonym.
- DataProcessors.BatchObjectsModification.Operations.AttributeName has "Attribute name (property)" synonym.
You can omit synonym prepositions and conjunctions in names. For example: DiscountMarkupValue attribute has "Discount or markup value" synonym.
You can also use shorter synonyms than names. In this case, you can abbreviate one or several "technical" words of the name.
Configuration objects and their presentations must be easily recognizable in the user interface. It facilitates the deployment procedure.
See also: Additional requirements for metadata object names in configurations
2.2. Metadata objects with the Obsolete prefix are exceptions.
Do not rename metadata objects, their attributes, forms, and so on if the objects must ensure backward compatibility. In particular, different library versions within a single revision must support backward compatibility with each other.
2.3. Metadata object names must not exceed 80 characters.
2.4. Do not use names identical to owner object names for subordinate metadata objects, such as attributes, dimensions, resources, and so on. For example, the User dimension of the CatalogRef.Users type of the TaskPerformers information register has an incorrect name. The correct dimension name is the following: Performer.
2.5. We recommend that you do not use names used for naming query language tables, for example, Document, Catalog, InformationRegister, and so on. Such names can cause query errors and make query design tricky and illegible. For example, this query causes an error:
SELECT
Info.Info
FROM
InformationRegister.Info AS Info
3.1. Specify Comments only when you need to explain the object purpose to other developers. For example, a comment to a catalog attribute can be as follows: "Indexing is used for optimizing reports filtered by a counterparty kind" and "Used in regulatory accounting".
3.2. Start your comments with a capital letter. Use periods only after abbreviations.
4. $$$