Procedure and function descriptions

This article describes the standards that apply to procedure and function descriptions. All of the listed recommendations are mandatory unless noted otherwise.

1. Describe procedures and functions by adding comments to the respective items. The developer is free to decide whether specific portions of procedure and function code should be commented based on their complexity and uniqueness.

On 1C:Enterprise version 8.3, the comment text is displayed in tooltips of procedures, functions, and their parameters. For more information, see section "Context tips during module text entry" in chapter 26 "Development tools" of 1C:Enterprise Developer Guide.

2. Procedures and functions that belong to program interface of modules are required to have comments. Such procedures and functions are intended to be used in other functional subsystems (or in other applications) that might be in the scope of responsibility of other developers, and they should, therefore, be properly documented.

This recommendation is optional

3. We recommend that you add comments to other procedures and functions (including event handlers belonging to form modules, object modules, record set modules, value manager modules, and so on) when explaining the purpose of a procedure or function or the specifics of its operation is required. We also recommend that you describe why a procedure or function does not perform certain actions when one might expect them to be performed.

However, you are not required to add a comment if a procedure or function is not difficult to understand and its purpose and operation are clear from its name and the names of its parameters.

4. Avoid comments that do not provide any additional explanation regarding the operation of a nonexport procedure or function.

Examples of incorrect comments:

// Handler of the "OnOpen" form event
// &AtClient
Procedure OnOpen()

// Handler of the "Calculate" command
// &AtClient 
Procedure Calculate()

// Handler of the "OnChange" event of the "EditInDialogOnly" form item
// &AtClient
Procedure EditInDialogOnlyOnChange(Item)

In these examples the comments are redundant because the names of the procedures imply that the procedures are event handlers. Their descriptions and parameter purposes are available in the Syntax Assistant.

// The function returns a cash flow item based on document data
Function CashFlowItem(DocumentData)

This comment does not provide any new information about the function.

5. Add your comments prior to the procedure or function declaration and format them as follows:

5.1. Description section. A brief verbal description of the purpose and/or operation of the procedure or function. It is the only section for procedures without parameters.

Example:

// Defines the availability of RoleNames roles to the current user,
// as well as the availability of administrator rights.

5.2. Parameters section. Describes procedure or function parameters. Skip this section if there are no parameters. Precede the section by the line "Parameters:".

5.2.1. The parameter description starts on a new line. The line has the following format: the parameter name, a hyphen, the list of types (*), a hyphen, and the parameter description.

Example:

// Parameters:
// RoleNames - String - comma-separated names of roles whose availability is checked.

5.2.2. For parameters of Structure and ValueTable types, add the descriptions of their properties and columns, each starting on a new line and preceded by * (asterisk).
Example:

// Parameters:
//   SeriesStatuses - ValueTable - a value table with the following columns:
//     * Series - CatalogRef.ItemSeries - if a series is specified and it cannot be used
                  with a new item value in the specified warehouse, returns the passed value;
                  otherwise returns an empty string.
//     * SeriesAvailabilityStatus - Number - if series are listed in the Items tabular section,
                  returns the calculated status; if the passed item or warehouse does not use
                  series, returns 0; otherwise returns the passed status.
// SeriesAvailabilityParameters - Structure - see ItemsClientServer.SeriesAvailabilityParameters

The same is true for parameters of Array type:

// Parameters:
//   UpdateInfo - Array - contains structures with the following properties:
//     * AddressObjectCode - String  - code of the address object.
//     * Description       - String  - description of the address object.
//     * Index             - String  - index of the address object.
//     * UpdateAvailable   - Boolean - shows whether an update is available.
//

Descriptions of arrays, structures, and value tables can have nested descriptions. Each level of nesting increases the number of asterisks before a property name: 2 asterisks for the first nested level, 3 for the second nested level, and so on.

// Parameters:
//   UpdateInfo - Array - contains structures with the following properties:
//     * AddressObjectCode - String  - code of the address object.
//       ** RegionCode          - Number - region code (2 characters).
//       ** TownCode            - Number - town code (3 characters).
//       ** StreetCode          - Number - street code (4 characters).
//     * Description       - String  - description of the address object.
//     * UpdateAvailable   - Boolean - shows whether an update is available.
//

5.2.3. For each parameter, you can specify one or several additional parameter type descriptions, each starting on a new line. The lines have the following format: a hyphen, a list of parameter types (*), a hyphen, and the type description.
Example:

// Parameters:
//   Attributes - String - attribute names, comma-separated.
//                         Example: "Code, Description, Parent".
//              - Structure, FixedStructure - the key is the alias of the field in the 
//                                            returned structure (which contains the result);
//                                            the value (optional) is the actual field name 
//                                            in the table.

//                                            If the value is not defined, the field name is
//                                            taken from the key.
//              - Array, FixedArray - array of attribute names.

5.3. Return value section. Describes the content and type of the return value of a function. Skip this section for procedures. Precede the section by the line "Returns:". The next line has the following format: the list of types (*), a hyphen, and the description of the return value.
Example:

// Returns:
// Boolean - True if at least one of the passed roles is available to the current user or the
//           current user has administrative rights.

Paragraphs 5.2.2 and 5.2.3 also apply to the return value section.

5.4. Example section. Provides a procedure or function usage example. Precede the section by the line "Example:".

5.5. In rare scenarios where several parameters have additional types, add the Call options section, which describes the call options with various combinations of parameter types (you can describe all available call options or just the most popular ones). Precede the section by the line "Call options:". Then provide the option descriptions, each on a new line. The option descriptions have the following format:
the function name with its parameters enclosed in parentheses, a hyphen, and a description of the call option.

Example:

// ...
//
// Parameters:
// Parameter1 - Type11, Type12 - ...
// Parameter2 - Type21, Type22, Type23 - ...
//
// Call options:
// UniversalProcedure(Type11, Type21) - description ...
// UniversalProcedure(Type12, Type22) - description ...
// UniversalProcedure(Type11, Type23) - description ...
//
Procedure UniversalProcedure(Parameter1, Parameter2) Export

5.6. We recommend that you use hyperlinks for quick switching to other configuration objects, modules, procedures, functions, and syntax assistant descriptions of platform types, objects, and methods. In particular, use hyperlinks for switching to structure constructor functions.

Precede a hyperlink with "see", "see procedure", "see function", or "see type", then provide a name. A name can be simple (one word) or complex (several words separated with periods).

5.6.1. Enclose hyperlink descriptions in parentheses:

// Parameters:
// SeriesStatuses - ValueTable - a value table with the following columns (see function SeriesClientServer.SeriesStatuses)

5.6.2. If the entire description is a hyperlink, omit the parentheses:

// Parameters:
// SeriesAvailabilityParameters - Structure - see ItemsClientServer.SeriesAvailabilityParameters

5.7. To mark a procedure or function obsolete, add "Obsolete" to the first line of its description.
Example:

// Obsolete. Use the new function (see CommonUse.RoleAvailable)
// ... 
Function RolesAvailable(RoleNames) Export

6. If you need to add a comment to a procedure or a function that is used with a compilation directive, add the comment prior to the compilation directive. Example:

// Procedure - handler of the "OnCreateAtServer" event of a form.
// Processes form parameters and fills the values of form attributes.
// It also executes the following actions:
// ...
//
&AtClient
Procedure OnCreateAtServer(Cancel, StandardProcessing)

This approach to commenting draws attention to the function definition and the compilation directive first, and only then to the comment (which might have many lines).

7. In the module text, separate the codes of procedures and functions by empty lines.

(*) Note. A list of types consists of comma-separated type names. A type name can be simple (one word) or complex (two words separated with a period).
Example: String, Structure, CatalogRef.Employees.

Examples of procedure and function descriptions

Example of a function with a single parameter:

// Defines the availability of RoleNames roles to the current user,
// as well as the availability of administrator rights.
//
// Parameters:
// RoleNames - String - comma-separated names of roles whose availability is checked.
//
// Returns:
// Boolean - True if at least one of the passed roles is available to the current user or the
// current user has administrative rights.
//
// Example:
// If RolesAvailable("UseReportMailingLists,SendMail") Then ...
//
Function RolesAvailable(RoleNames) Export

Example of a procedure without parameters:

// The BeforeWrite handler of a document includes the following actions:
// - clear the service tabular section if the consignor contract is specified;
// - check whether the MeasurementUnit attribute of the Items tabular section is filled;
// - synchronize items tabular section data with a linked sales invoice;
// - fill warehouse and customer order in the Items and Empties tabular sections;
// - remove unfilled rows of the "Serial numbers" tabular section;
// - fill the DeleteRegisterRecords variable of the object module.
//
Procedure BeforeWrite()
EndProcedure

Autoordering comments to procedures and functions with compilation directives

You can use the FormatProcedureComments.epf data processor to move procedure or function comments to the area before the compilation directive.

Dump the configuration to files (on the Configuration menu, click Dump configuration files).
Open the data processor in 1C:Enterprise mode, select the directory that stores the dumped files, and click Format.
Load the modules back to the configuration (on the Configuration menu, click Restore configuration from files).

Next page: Procedure and function names