Names, synonyms, and comments

Scope: managed applications, mobile applications, and ordinary applications.

1.1. Synonyms must be short and descriptive and provide users with the object's purpose. Synonym is required for every object.

The reason is that a synonym is basically the object's display name. It appears in the user interface—forms, reports, command interfaces—and to deliver its purpose, it must unambiguously identify the entity it represents. This applies to metadata objects, tabular sections, metadata objects' and tabular sections' attributes, register dimensions, resources, and any other configuration object that has a synonym.

1.2. Avoid abbreviating synonyms, except for widely used abbreviations, such as CEO, VAT, or IFRS.

1.3. Synonyms should contain conventional words, understandable by the end-users. Do not use slang, jargon, or informal words.

Use the end-user language, except for conventionally used English words, such as company names and product names.
Incorrect: "Exporter des données de Exceller."
Correct: "Exporter des données de Microsoft Excel."

1.4. If a metadata object has standard attributes or standard tabular sections, their synonyms are required.

1.5. For standard attributes Parent and Owner, always rename the default synonyms. For example, catalog Files has standard attribute Owner of the CatalogRef.FilesFolders type.
Incorrect synonym:

"Owner". This would be misleading for the end-users.

Correct synonym:

"Folder" or "File directory". The end-users can easily deduce the purpose of the attribute.

Another example. While for some catalogs the default "Description" synonym might be suitable for the Description attribute, for most catalogs you should customize it. For example, for a catalog named Files, the synonym could be "File name", and for the Employees catalog, "Full name".

1.6. If a configuration contains multiple similar metadata objects, make sure their synonyms unambiguously define the objects.

Incorrect synonyms:

Bank accounts
Counterparty bank accounts

Correct synonyms:

Company bank accounts
Counterparty bank accounts

In the first case, the end-users might get confused: "If the Counterparty bank accounts catalog stores bank accounts of counterparties, what accounts are stored in Bank accounts?"

This requirement also applies to the synonyms of subordinate metadata objects, such as attributes, tabular sections, dimensions, and resources.
For example, a configuration contains document Inventory count with the Goods tabular section.
Incorrect attribute synonyms:

Quantity
Quantity (recorded)

Correct attribute synonyms:

Quantity (actual)
Quantity (recorded)

Another example. The Products catalog contains the standard Description attribute and a similar attribute.
Incorrect synonyms:

Description
Full description

Correct synonyms:

Internal description
Printable description

2.1. It is recommended that an object's Name match its synonym with the following changes: spaces and invalid characters are removed, the initial letters are capitalized.
Incorrect:

AdditionalAttributesAndRecords — Additional items
AttachedFiles — Attachments

Correct:

AdditionalAttributesAndRecords — Additional attributes and records
AttachedFiles — Attached files

When you create a name, it is acceptable to omit insignificant or refining words used in the object synonym. For example:

ServerTimeout — Server timeout (sec)
UnitsCount — Measurement units count
DataProcessors.BatchObjectsModification.Operations.AttributeName — Attribute name (property)

It is acceptable to omit prepositions and conjunctions in names, too. For example: InventoryIncreaseDecrease — Inventory increase or decrease.

To make synonyms more user-friendly, it is acceptable to omit some technical terms used in the object names.

See also: Names of metadata objects

2.2. The recommendations mentioned in 2.1 are not applied to metadata objects with the Obsolete prefix.

Also, do not rename metadata objects that ensure backward compatibility. For example, if you develop a library, make sure that all library versions with the same major and minor version numbers are backward-compatible.

2.3. Metadata object names must not exceed 80 characters.

2.4. In most cases, the name of an object should not match the name of the object it references to. For example, information register TaskAssignees has a dimension of the CatalogRef.Users type. Incorrect name for the dimension: User. The correct name: Assignee.

2.5. When you name an object, it is recommended that you do not use names of query language tables, such as Document, Catalog, and InformationRegister. This might lead to query errors and will make the usage of Query Wizard more complicated. For example, this query causes an error:

SELECT
Info.Info
FROM
InformationRegister.Info AS Info

3.1. Use the Comment field only when you want to provide developers with details on the object. Examples of comments to catalog attributes: 1. "Indexing provided to optimize counterparty kind filters." 2. "Used in regulatory accounting."

3.2. The first word of a comment is capitalized.

3.3 If a comment is a complete sentence, end it with a period.

See also:

<< Prev Next >>