Describing procedures and functions

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

1. We recommend that you describe the purpose of procedures and functions as a comment. As an application developer, you need to assess the difficulty, readability, and understandability of the code block and consider leaving a comment.

In 1C:Enterprise 8.3 platform, comments are also displayed as tooltips to procedures, functions, and parameters.

In 1C:Enterprise Development Tools (EDT), you can leave comments to describe parameters and return values of procedures and functions, which helps to identify code errors at the development stage.

2. In the module API, procedures and functions require comments. Properly document such procedures and functions since they might be used in other subsystems or applications developed or operated by third parties.

See also: Restrictions on export procedures and functions and Creating form modules

3. Leave documentation comments on other procedures and functions if you think their purpose or behavior might be unclear to the reader. Besides describing what a function or procedure does, sometimes it is reasonable to describe what it does not do.

You do not need to comment code if it is self-documenting, that is, the procedure or function is somewhat trivial, and its purpose and behavior can be deduced from the names of the parameters, variables, and so on.

4. Do not leave comments that do not add value to the code, that is, do not help the reader to understand the procedure or function better.
Incorrect:

// "OnOpen" event handler of the form.

&AtClient

Procedure OnOpen()

// "Calculate" command handler.

&AtClient

Procedure Calculate()

// "OnChange" event handler of the "EditInDialogOnly" form item.

&AtClient

Procedure EditInDialogOnlyOnChange(Item)

These comments are redundant since the names of the procedures clearly describe that their purpose is to handle events. Besides, the reader can find detailed information on the procedures and their parameters in Syntax Assistant.

// The function returns a cash flow item from a document.

Function CashFlowItem(DocumentData)

The comment does not provide the reader with any additional details on that function.

5. Place a comment at the top of the function or procedure. Stick to the following comment structure:

5.1. In the Description section, explain the purpose of the procedure or function in a short, but clear way, so that the reader would understand its behavior without looking into the source code. Here, you can also include the description of its mechanics and links to related procedures and functions.

If the procedure or function has no parameters, this can be the only comment section. The description text cannot be identical to the name of the function or procedure. Start the description with a verb. For functions, the description usually starts with "Returns." If returning a result is not the main purpose of the function, start the section with a verb that describes the main purpose. For example, "Validates," "Compares," or "Calculates." Do not start the description with excessive words like "Procedure", "Function", or its name.

Incorrect:

// WSProxy constructor.

// ...

Function WSProxy(ProxyParameters) Export

// Function ValueTableRowToStructure creates a structure with properties inherited from...

Function ValueTableRowToStructure(ValueTableRow) Export

Correct:

// Creates a proxy based on the web service definition and

// connects it to the web service.

// As an addition to the platform constructor, New WSProxy:

// - calls WSDefinitions constructor.

// - caches the WSDL file to reduce the number of web service calls.

// - does not require to specify InternetProxy explicitly. It is populated automatically.

// - checks the web service for accessibility with the Ping function.

// ...

Function WSProxy(ProxyParameters) Export

// Creates a structure with the properties inherited from...

Function ValueTableRowToStructure(ValueTableRow) Export

5.2. In the Parameters section, describe the parameters of the procedure or function. The section is omitted if there are no parameters. Start the section with "Parameters:". Place each parameter on a new line.

5.2.1. To describe a Parameter, stick to the following structure: 1) parameter name, 2) hyphen, 3) list of types*, 4) hyphen, and 5) parameter description.

Choose a parameter name that clearly conveys its purpose and requires no further explanation.

Parameter type is required. The type can be described explicitly. You can specify either one type or a list of types. The list of types contains comma-separated types the parameter supports. A type name can be simple (one word) or composite (two comma-separated words).
For example: String, Structure, Arbitrary, CatalogRef.Employees.

Specify only valid 1C:Enterprise types and special types provided in EDT. For example: DefinedType.<Name>, CatalogRef, MetadataObjectReport, FormDecorationExtensionForLabel.

Incorrect:

// RowCollection - ValueCollection - A collection for comparison;

// ReportToGenerate - MetadataObject: Report

// AttachedFileObject - A file catalog item.

Correct:

// RowCollection - ValueTable, Array, ValueList - A collection for comparison.

// ReportToGenerate - MetadataObjectReport

// AttachedFileObject - DefinedType.AttachedFileObject - A file catalog item.

Parameters do not require a description unless you consider it reasonable to provide the reader with additional details about their purpose. You can also give an example of its valid value.

Incorrect:

// Checks whether the passed addresses are included in the task. If the check fails, an exception is thrown.
//
//Parameters:
// Addresses - String - A string that contains email addresses.
// PerformerTask - TaskRef.PerformerTask - A task to be checked.
//
ProcedureCheckTaskAddresses(Addresses, PerformerTask)

Correct:

// Checks whether the passed addresses are included in the task. If the check fails, an exception is thrown.
//
// Parameters:
// Addresses - String - Contains comma-separated email addresses. For example, support@mycorp.com,v8@localdomain.
// PerformerTask - TaskRef.PerformerTask
//
Procedure CheckTaskAddresses(Addresses, PerformerTask)

This example provides the description for the "Addresses" parameter to:

Specify the rule for passing several addresses (separated by a comma).
Give an example.

The PerformerTask parameter does not require a description.

5.2.2. For the Structure and ValueTable types, specify a reference to the function whose output value is this structure or value table. For example, give a reference to a constructor function.

Example:

// Populates prices in a table row.
// Parameters:
// CurrentRow - LineOfATabularSection
// PriceFillingParameters - See PricingServer.PriceFillingParameters
//
Procedure FillPricesInTSRow(CurrentRow, PriceFillingParameters);

For methods that process collections universally, there is no need to describe the parameter properties and columns. Instead, specify the Structure or ValueTable (ValueTree) type.

5.2.3. For the Array type, specify a type of its elements using the of keyword.

Incorrect:

// ForwardedTasksArray - Array - An array of forwarded tasks.

// ForwardedTasksArray - Array - Tasks (TaskRef.PerformerTask) forwarded to another assignee.

Correct:
// UpdateInfo - Array of See InfobaseUpdate.UpdateParameters

Methods that operate with arrays in a universal manner do not require specification of an array element type. For example, SupplementArray and DeleteAllValueOccurrencesFromArray methods in Standard Subsystem Library.

5.2.4. For the ValueTableRow (ValueTreeRow) type, you can set a list of properties that correspond to columns in the owner table (owner tree):
Example:

// RegionInfo - ValueTableRow: See InformationRegisters.AddressObjects.TerritorialEntityClassifier

In this example, TerritorialEntityClassifier is an export function of the AddressObjects information register manager module that returns a value table.

5.2.5. You can provide a parameter with the description of its types. Place each parameter on a new line and stick to the following structure: 1) hyphen, 2) list of parameter types, 3) hyphen, and 4) description.
Example:

// Parameters:

// Attributes - String - Comma-separated attribute names.

// Example: "Code, Description, Parent".

// - Structure, FixedStructure - The field alias of the returned structure

// is passed as a key, and

// (optionally) the field name is passed as a value.

// If the value is undefined, the key value is used.

// - Array Of String, FixedArray Of String - Attribute names.

5.2.6. You can set a parameter description using a reference to the constructor function in the format "see MethodPath").
Example:

// SeriesSpecificationParameters - See ProductsClientServer.SeriesSpecificationParameters
// Duplicates - See DataProcessorObject.DuplicateObjectsDetection.DuplicatesGroups
// AddInAttributes - Array of See AddIns.AddInAttributes

When developing code to access attributes of a specific metadata object or form, you can refer to the attribute types of this object or form:

// Queries - See DataProcessors.QueryConsole.TabularSection.Queries
// DataTypes - See DataProcessors.QueryConsole.Attribute.AvailableDataTypes
// Attachments - See Catalogs.MessageTemplates.ItemForm.Attachments
// ContactInformation - See Documents.SalesOrder.DocumentForm.Object.ContactInformation

If a suitable constructor function does not exist and cannot be created, specify a reference to another procedure (provided the parameters match) or to a parameter of another procedure or function. Example:

// See AttachableCommandsOverridable.OnDefineCommandsAttachedToObject
//
Procedure OnDefineCommandsAttachedToObject(FormSettings, Sources, AttachedReportsAndDataProcessors, Commands) Export

// Parameters:
// FormSettings - See AttachableCommandsOverridable.OnDefineCommandsAttachedToObject.FormSettings
// Sources - See AttachableCommandsOverridable.OnDefineCommandsAttachedToObject.Sources
// AttachedReportsAndDataProcessors - See AttachableCommandsOverridable.OnDefineCommandsAttachedToObject.AttachedReportsAndDataProcessors
// Commands - See AttachableCommandsOverridable.OnDefineCommandsAttachedToObject.Commands
//
Procedure OnDefineCommandsAttachedToObject(FormSettings, Sources, AttachedReportsAndDataProcessors, Commands) Export

5.3. In the Returns section, describe the type and content of the function return value. Omit this section if you describe a procedure. Start the section with "Returns:". Place each type on a new line and stick to the following structure: 1) type, 2) hyphen, and 3) description. For composite types, place each type on a new line and start with a hyphen. Example:

// Returns:

// String

// Returns:

// Boolean - True if the user is granted with at least one of the passed roles or with the administrator rights.

// Returns:

// - AnyRef - A reference to the predefined item.

// - Undefined - If the predefined item exists in metadata but not created in the infobase.

// Returns:

// - CatalogRef.Users

// - CatalogRef.ExternalUsers

Return values do not require description unless you consider it reasonable to provide the reader with additional details such as the list of properties or columns a return value contains. You can also provide an example of a valid return value or place it in the Example section.
The requirements from 5.2.3 are also applicable to return values of the Array type.
To describe return values of the Structure and ValueTable types, see Using structures as procedure and function parameters.

5.4. In the Example section, provide a use case for the procedure or function. Start the section with "Example:". Place each example on a new line. Place the function or procedure name to the end of its module name separated by a dot. The example must clearly show inputs and outputs.
For example, the following is incorrect:

// Example:

// SubstituteParametersToString(StringPattern, ReplacementString);

Correct:

// Example:

// StringFunctionsClientServer.SubstituteParametersToString(NStr("en='The %1 document is missing the %2 attribute'"), "Sales invoice", "Currency") = "The Sales invoice document is missing the Currency attribute".

5.4.1. For overridable modules in the Example section, do not provide an example of the overridable procedure call. Instead, provide an example of the overridable procedure implementation. Example for the OnDetermineCommonCoreParameters(CommonParameters) procedure:

// Example:

// CommonParameters.MinPlatformVersion = "8.3.4.365";

// CommonParameters.RecommendedRAM = 2;

5.5. If a few parameters support multiple value types, it is recommended that you provide the Call options section. In the section, describe all or the most frequent combinations of parameter types. Start the section with "Call options:". Place each option on a new line and stick to the following structure: 1) function name, 2) opening round bracket, 3) list of comma-separated parameters, 4) closing round bracket, 5) hyphen, and 6) description.

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. In any part of a documentation comment, you can provide a link to another configuration object, such as constructor functions. If you use 1C:Enterprise Development Tools, it will convert the link into a hyperlink.
Example:

// Universal procedure description.

// See AccessManagement.FillAccessValuesSets

// Parameters:

// Parameter1 - Arbitrary - See the parameter description in Catalog.Counterparties.

Procedure UniversalProcedure(Parameter1)

5.7. If you need to mark a procedure or a function as deprecated, the first line of its details will contain the word "Deprecated".
Example:

// Deprecated. Use Common.DataSeparationEnabled and

// Common.SeparatedDataUsageAvailable

// ...

Function SessionSeparatorUsage() Export

6. When you comment on a procedure or function that has a compilation directive, do not break them with a comment. Always place the comment before the directive.
Example:

// Procedure - The OnCreateAtServer event handler.

// Processes form parameters and populates form attributes with values.

// Other features:

// ...

&AtServer

Procedure OnCreateAtServer(Cancel, StandardProcessing)

Such layout makes code more readable and helps the reader to easily distinguish the compilation directive and function definition from the preceding comment.

7. Separate the code of a procedure or function from other procedures and functions with a single blank line.

Examples of commenting on procedures and functions

Description of a function with a single parameter:

// Determines if the RolesNames and administration rights

// are available to the current user.

// Parameters:

// RolesNames - String - A list of comma-separated roles to be checked.

// Returns:

// Boolean - True if the user is granted with at least one of the roles

// or with the administration rights.

// Example:

// If RolesAvailable("UseReportsDistribution,SendByEmail) Then...

Function RolesAvailable(RolesNames) Export

Description of a procedure with no parameters:

// The BeforeWrite event handler:

// - Cleans up the service table if an agreement is specified.

// - Checks if the UnitUOM attribute is filled in the Goods table.

// - Synchronizes with the subordinate proforma invoice.

// - Populates the warehouse and sales order values in the Goods and ReturnablePackage tables.

// - Deletes unused rows in the "Serial numbers" table.

// - Populates the DeleteRegisterRecord object module variable.

Procedure BeforeWrite()

EndProcedure