Scope: managed applications, mobile applications, and ordinary applications.
1. We recommend that you describe the purpose of procedures and functions as a block comment. As an application developer, you have 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, 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 API modules, export 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.
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, unless obvious, it's reasonable to describe what it doesn't do.
You don't have to comment code if it's 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.
// "OnOpen" event handler // &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. On the other hand, the reader can find detailed information on the procedures and their parameters in Syntax Assistant.
// The function returns the cash flow item from a document Function CashFlowItem(DocumentData)
The comment doesn't 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 must not be identical to the name of the function or procedure. Start the description with a verb. For functions, usually, the description 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." Don't start the description with excessive words like "Procedure" or its name.
// WSProxy constructor. // ... Function WSProxy(ProxyParameters) Export // Function ValueTableRowToStructure creates a structure with properties inherited from... Function ValueTableRowToStructure(ValueTableRow) Export
// 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. If it has no parameters, omit this section. Start the section with the headline "Parameters:". Place each parameter on a new line.
5.2.1. To describe a Parameter, stick to the following structure: 1) the parameter name, 2) a hyphen, 3) the list of types*, 4) a hyphen, and 5) the parameter's description. In parameter's description, provide detailed information, explain its purpose and, optionally, give an example of its valid value.
// String - String - a string that contains email addresses. // TaskRef - TaskRef.PerformerTask - a task.
// Addresses - String - a string that contains comma-separated email addresses. For example, "firstname.lastname@example.org, v8@localdomain". // PerformerTask - TaskRef.PerformerTask - the task to be checked.
* Note. A list of types contains comma-separated types the parameter supports. A 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. Incorrect:
// RowCollection - ValueCollection - a collection for comparison.
// RowCollection - ValueTable, Array, ValueList - an item for comparison.
// Parameters: // SeriesStatuses - ValueTable - a table with the following columns: // * Series - CatalogRef.ProductsSeries - if a series is specified and // it supports the new product value at the specified warehouse, // returns the passed value. Otherwise, returns an empty reference. // * SeriesAsignmentStatus - Number - if the Goods tabular section is assigned with series, // returns the calculated status. If the passed product ID // doesn't support series, returns zero. // Otherwise, returns the passed status.
// ForwardedTasksArray - Array - an array of forwarded tasks. // ForwardedTasksArray - Array - the tasks (TaskRef.PerformerTask) forwarded to another assignee.
// ForwardedTasks - Array contains TaskRef.PerformerTask - tasks forwarded to another assignee. // Parameters: // UpdateInfo - Array contains Structure - where: // * AddressObjectCode - String - the address object code. // * Description - String - the description of the address object. // * PostalCode - String - the postal code of the address object. // * UpdateAvailable - Boolean - if True, an update is available. //
You can provide arrays, structures, and tables with nested descriptions. The Nth nested level starts with N+1 number of asterisk: 2 asterisks for the first nested level, 3 for the second, and so on.
// Parameters: // UpdateInfo - Array contains Structure - where: // * AddressObjectCode - Structure - the address object code: // ** StateCode - Number - the state code, 2 digits. // ** LocalityCode - Number - the locality code, 3 digits. // ** StreetCode - Number - the street code, 4 digits. // * Description - String - the description of the address object. // * UpdateAvailable - Boolean - if True, an update is available. //
5.2.4. 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) a hyphen, 2) parameter types, 3) a hyphen, and 4) the description.
// 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 // (optional) the field name is passed as a value. // If the value is not defined, the key value is used. // - Array, FixedArray - the attribute names (String).
// SeriesSpecificationParameters - see ProductsClientServer.SeriesSpecificationParameters. // AddInAttributes - see AddInsInternal.AddInAttributes.
5.3. In the Returns section, describe the type and content of the return value. Omit this section if you describe a procedure. Start the section with the headline "Returns:". Place each type on a new line and stick to the following structure: 1) a type, 2) a hyphen, and 3) the 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 - the reference to the predefined item. // - Undefined - if the predefined item exists in metadata, but not missing in the infobase. // Returns: // - CatalogRef.Users // - CatalogRef.ExternalUsers
Return values don't 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.2 and 5.2.3 are also applicable to return values.
5.4. In the Example section, provide a use case for the procedure or function. Start the section with the headline "Example:". Place each example on a new line. Append the function or procedure name to the end of its module name, separated by a dot. In the example, provide instances of passed and returned values.
// Example: // SubstituteParametersToString(StringPattern, ReplacementString);
// Example: // StringFunctionsClientServer.SubstituteParametersToString(NStr("en='Document %1 is missing attribute %2.'"), "Sales invoice", "Currency") = "Document Sales invoice is missing attribute Currency."
5.4.1. For overridable modules in the Example section, don't 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 = "188.8.131.525"; // 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 the headline "Call options:". Place each option on a new line and stick to the following structure: 1) the function name, 2) an open round bracket, 3) the list of comma-separated parameters, 4) a closed round bracket, 5) a hyphen, and 6) the description.
// ... // // 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 clickable hyperlink.
// Universal procedure description. // // See AccessManagement.FillAccessValuesSets // // Parameters: // Parameter1 - Arbitrary - see the parameter description in Catalog.Counterparties. // Procedure UniversalProcedure(Parameter1)
// Deprecated. Instead, use Common.HasRole // ... Function RolesAvailable(RolesNames) Export
// Procedure - OnCreateAtServer event handler. // Processes form parameters and populates form attributes with values. // Other features: // ... // &AtServer Procedure OnCreateAtServer(Cancel, StandardProcessing)
Such a layout makes code more readable and helps the reader to easily distinguish the compilation directive and function definition from the preceding comment.
Examples of commenting on procedures and functions
Description of a function with a single parameter:
// Determines if the RolesNames and administrative rights // are available to the current user. // // Parameters: // RolesNames - String - the 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 administrative 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 tabular section if an agreement is specified. // - Checks if the UnitUOM attribute is filled in the Goods tabular section. // - Synchronizes with the subordinate proforma invoice. // - Populates the warehouse and sales order values in the Goods and ReturnablePackage tabular sections. // - Deletes unused rows in the Serial numbers tabular section. // - Populates the DeleteRegisterRecord object module variable. // Procedure BeforeWrite() EndProcedure
To auto-arrange comments for procedures and functions that have compilation directives, run the CompilationDirectivesFormatting.epf data processor.
To do this:
- Open the configuration in Designer mode. In the menu, select Configuration — Dump configuration to files... Choose a directory and select Run.
- Open the data processor in 1C:Enterprise mode, specify the directory that contains the files, and then select Format.
- Open the configuration in Designer mode. In the menu, select Configuration — Restore configuration from files... Select the directory that contains the files and select Run.