Module formatting

• Procedure and function names
• Procedure and function descriptions
• Considerations on using structures as parameters of procedures and functions
• Procedure and function parameters
• Rules of naming variables
• Module structure
• Module texts
• Writing register records

Procedure and function names

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

1. Proper naming of procedures and functions is very important because it makes the code easier to read. In most cases, a good procedure name combined with properly selected parameter names will eliminate any need to further describe the procedure. In some situations, difficulties in selecting names for a procedure and/or its parameters reveal poor programming code architecture. The opposite is also true: if it is easy to come up with a "self-documenting" name, then the procedure has been properly designed.

See also: Procedure and function descriptions

2. Parameters, functions, and formal parameters should be named based on the terms of the subject area so that the name makes the purpose clear. Try to make the names "self-describing".
Incorrect:

Function Check(Parameter1, Attr, TS)
Function GetAttributeArrays(BusinessTransaction, AllAttributesArray, TransactionAttributesArray)

Correct:

Function SpecifiedObjectTypeAttribute(Object, AttributeName, ValueType)
Function FillAttributeNamesByBusinessOperation(BusinessOperation, AllAttributeNames, OperationAttributeNames)

3. Names should be generated by deleting spaces that separate the words. Note that every word in the name should then be capitalized. Prepositions and pronouns that consist of a single letter are also capitalized.

Function GetArrayOfRolesWithAddRight()
Function GetAggitionalSettingsStructure()

Function NamesOfRolesWithAddRight()
Function AdditionalSettings()

Function GetFullUserName()
Function CreateVendorPriceFillingParameters() 
Function DefineSessionStartDate()

Function FullUserName()
Function NewVendorPriceFillingParameters()
Function SessionStartDate()

Function AddFormField()
Function CreateFilesCatalogItem()
Function GetCommandTable()

Function NewFormField()
Function NewFilesCatalogItem()
Function NewCommandTable()

Function CheckIfDocumentIsPosted()
Function CheckIfDocumentAttributesChanged()
Function ExternalTask()

Function DocumentPosted()
Function DocumentAttributedModified()
Function IsExternalTask()

Function SelectDataByRule(Rule, UserSettings)
Function ConvertDataByRule(DataSets, ConversionParameters)

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.

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 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 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.

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

Considerations on using structures as parameters of procedures and functions

Main article: Procedure and function parameters 

When dealing with procedures and functions (referred to further as functions) that have parameters of the Structure type, we recommend following the approach to development as described below.

1. In addition to the function that implements the application functionality (the function that is called), define a constructor function for creating a structure (the constructor of parameters). In this case, the constructor function does not accept any parameters and only returns a blank structure with properties. The code that calls the function initializes the structure with specific values and then passes it to the function being called.

Sample code that calls the function:

Procedure OnItemChangeServer(CurrentRowID)

// Getting new parameter structure.
PriceFillingParameters = PricingClientServer.TSRowPriceFillingParameters(); 

// Filling parameters.
PriceFillingParameters.Date = Object.Date;
PriceFillingParameters.Currency = Object.Currency;

CurrentRow = Object.Items.FindByID(CurrentRowID);

// Passing parameter structure to the applied function.
PricingServer.FillPricesInTSRow(CurrentRow, PriceFillingParameters);

Example of parameter constructor function in PricingClientServer module:

Function TSRowPriceFillingParameters() Export
 
 PriceFillingParameters = New Structure;
 PriceFillingParameters.Insert("Date");
 PriceFillingParameters.Insert("Currency");
 PriceFillingParameters.Insert("RecalculateAmount", True);
 PriceFillingParameters.Insert("RequiredParameters","Date,Currency"); // required parameters that must be filled
 Return PriceFillingParameters;
 
EndFunction

The names of structure properties correspond to the parameters of the called function. Note that any parameters with default values should be explicitly initialized in this structure.

2. Do not add any other properties to the parameter structure in the calling code. In order to avoid ambiguity and hidden errors, all valid parameters of the called function should be explicitly defined in the parameter constructor function.

Procedure and function parameters

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

1. When you declare formal parameters of procedures and functions (hereafter referred as functions), follow general variable naming rules. In particular, parameter names must be based on the terms of the subject area so that the parameter name clearly describes its purpose.

2. Do not use other configuration parameters (module variables, form attributes, etc.) in place of function parameters.

3.1. Function parameters should be ordered reasonably. It is recommended that you arrange parameters from the most general ones to the most specific ones.

Incorrect:

Procedure RecalculateDocumentTotal(AmountFieldName, DocumentObject, AmountIncludesVAT = True)
Procedure ChangeFormFieldColor(Color, FieldName, Form)

Correct:

Place major parameters DocumentObject and Form first.

Procedure RecalculateDocumentTotal(DocumentObject, AmountFieldName, AmountIncludesVAT = True)
Procedure ChangeFormFieldColor(Form, FieldName,Color)

3.2. Optional parameters (those having default values) must follow parameters that do not have default values.

Example:

Function CurrencyExchangeRateForDate(Currency, Date = Undefined) Export

4. We do not recommend declaring too many parameters in functions (avoid implementing functions with more than seven parameters). Also avoid using too many parameters with default values (we recommend no more than three). Otherwise the code that calls the function becomes much more difficult to read. For example, you can easily make a mistake in the number of commas when you pass optional parameters to a function. 

If you need to pass numerous parameters into a function, we recommend that you:

• combine similar parameters into parameters of Structure type. For example, structures can store parameters that describe the fields of a certain object and their values (FillingData, PostingParameters, FileData, and so on);
• or completely rework the function logic, for example by splitting it into multiple simpler functions.

Incorrect:

// Adds a new field to a form and initializes it with default values.
Function AddFormField(Name,
      Heading = Undefined,
      OnChangeHandler = "",
      OnBeginSelectionHandler = "",
      MarginWidth,
      Backcolor = Undefined,
      TitleBackColor = Undefined,
      Parent = Undefined,
      HeaderPicture = Undefined,
      DataPath = Undefined,
      FieldReadOnly = False,
      ChoiceParameterLinks = Undefined)
…
EndFunction

// calling the function
NewField = AddFormField("OldPrice" + ColumnName, NStr("en='Price'"),,, 12, BackColor, TitleColor, NewFolder,,,True);
NewField.TextColor = WebColors.Gray;

Correct:

Redesign the function logic and only keep a single key parameter FieldName:

// Adds a new field to a form and initializes it with default values.
Function NewFormField(FieldName) 
…
EndFunction

// calling the function
NewField = NewFormField("OldPrice" + ColumnName);
NewField.Heading = NStr("en='Price'");
NewField.BackColor = BackColor;
NewField.TextColor = WebColors.Gray;
NewField.… = …
…

Incorrect:

// Creates an item in the "Items" catalog
Procedure CreateItemsItem(Description, ProductService, UnitOfMeasurement, NetWeight, CheckUniqueness = True)
…
EndProcedure

Correct:

Combine the parameters that describe values of product attributes into a structure named AttributeValues:

// Creates an item in the "Items" catalog
Procedure CreateItemsItem(AttributeValues, CheckUniqueness = True)
…
EndProcedure

5. When you call functions, avoid bulky structures, which make the code harder to understand, increase the risk of errors, and hinder debugging.

5.1. When you pass parameters to a function, we recommended that you do not use nested calls of other functions.

Incorrect:

AttachmentsStructure.Insert(
  AttachedFile.Description,
  New Picture(GetFromTempStorage(
  AttachedFiles.GetFileData(AttachedFile.Ref).FileBinaryDataRef)));

Correct:

Split such calls into separate statements and use auxiliary local variables:

PictureFileAddress = AttachedFiles.GetFileData(AttachedFile.Ref).FileBinaryDataRef;
PictureData = New Picture(GetFromTempStorage(PictureFileAddress));
AttachmentsStructure.Insert(AttachedFile.Description, PictureData);

Note that when the code containing nested calls is compact (i.e., does not require statements to be wrapped) and easily readable, such nested calls are allowed.

Example:

DoMessageBox(NStr("en='To perform this action, you have to install the file system extension.'"));
RecalculateAmountByExchangeRate(Amount, CurrencyExchangeRateForDate(Currency));

5.2. It is recommended that you do not use nested structure constructor when calling functions: New Structure(...). Nested declaration of a structure is only allowed when it has a few properties (aim for a maximum of three).

Incorrect:

FillPrices(
  Object.Goods, // Tabular section
  , // String array or filter structure
  New Structure( // Filling parameters
   "Date, Currency, Agreement, FieldsToBeFilled",
   Object.Date,
   Object.Currency,
   Object.Agreement,
   "Price, VATRate, PriceKind, DeliveryDate"
  ),
  New Structure( // Structure of operations on modified line items
   "RecalculateAmount, RecalculateAmountWithVAT, RecalculateVAT, RecalculateAdjustedDiscountAmount, ClearAutomaticDiscount, ClearMutualSettlementAmount",
   "PacksQuantity", AmountRecalculationStructure, AmountRecalculationStructure, "PacksQuantity", Undefined, Undefined
  )
 );

Correct:

FillingParameters = New Structure; 
FillingParameters.Insert("Date", Object.Date); 
FillingParameters.Insert("Currency", Object.Currency); 
FillingParameters.Insert("Agreement", Object.Agreement); 
FillingParameters.Insert("FieldsToBeFilled", "Price, VATRate, PriceKind, DeliveryDate");

ActionsOnModifiedRows = New Structure; 
ActionsOnModifiedRows.Insert("RecalculateAmount","PacksQuantity"); 
ActionsOnModifiedRows.Insert("RecalculateAmountWithVAT", AmountRecalculationParameters); 
ActionsOnModifiedRows.Insert("RecalculateVAT", AmountRecalculationParameters); 
ActionsOnModifiedRows.Insert("RecalculateAdjustedDiscountAmount","PacksQuantity"); 
ActionsOnModifiedRows.Insert("ClearAutomaticDiscount"); 
ActionsOnModifiedRows.Insert("ClearMutualSettlementAmount"); 
FillPrices(Object.Items, FillingParameters, ActionsOnModifiedRows);

See also:

• Passing parameters to procedures and functions by reference and by value
• Considerations on using structures as parameters of procedures and functions
  

Rules of naming variables

This article describes the standards that apply to variable names. All of the listed recommendations are mandatory unless noted otherwise.

1. Name your variables based on the terms of the subject area, so that the variable name clearly describes its purpose.

2. Create variable names by deleting spaces that separate the words. Capitalize each word in the name, including prepositions and pronouns that consist of a single letter.

Example:

Variable DirectoryProcessingDialog; // Dialog to work with a directory
Variable PacksInBoxQuantity; // Number of packs in a box

Examples of incorrect variable names:

maxAttributes, matchTypeName, newStr

3. Do not begin variable names with an underscore.

4. Do not use variable names that consist of a single character. Short variable names are only allowed for loop counters.

5. Name variables that describe binary states ("true" or "false") after the state that matches the "true" value.

Example:

Variable HasErrors; // Shows whether procedure contains errors.
Variable IsReusableContainer; // Shows whether a product is a reusable container.

See also:

• Using global variables in modules

Module structure

This article describes the standards that apply to module structure. All of the listed recommendations are mandatory unless noted otherwise.

1.1. A program module (common module, object module, object manager module, form module, command module, and so on) can have the following sections ordered as listed below:

• module header
• variable description section
• export procedures and functions of the module, which comprise its program interface
• event handlers of an object (form)
• internal procedures and functions of the module
• initialization section

Some sections only appear in modules of specific types. For example, event handlers of form items can only exist in form modules, while the variable description and initialization sections cannot be defined in nonglobal common modules, object manager modules, record set modules, constant value modules, or the session module.

Dividing the module code into sections makes the code easier to read and modify for different authors (developers), both during group development and during application customization within specific deployment projects.

1.2. Split large module sections into subsections based on their functionality.

1.3. In configurations developed for platform version 8.2 or earlier, mark module sections and subsections with comments (see the description of the comment format below). There are no restrictions for section and subsection names.

In configurations developed for platform version 8.3, sections and subsections are marked as regions. The region names must comply with the Rules of naming variables standard.

1.4. The following is the section template for common modules. You are free to copy it for use in your modules.

For platform version 8.2 or earlier

////////////////////////////////////////////////////////////////////////////////
// <Module header: a brief description of the module and when it is used.>
// 
////////////////////////////////////////////////////////////////////////////////

////////////////////////////////////////////////////////////////////////////////
// INTERFACE

////////////////////////////////////////////////////////////////////////////////
// INTERNAL PROCEDURES AND FUNCTIONS 

For platform version 8.3

////////////////////////////////////////////////////////////////////////////////
// <Module header: a brief description of the module and when it is used.>//
////////////////////////////////////////////////////////////////////////////////

#Region Interface
// Procedure and function code
#EndRegion

#Region InternalProceduresAndFunctions
// Procedure and function code
#EndRegion

• The Interface section contains export procedures and functions intended for use by other configuration objects or by other programs (for example, via an external connection).
• The Internal procedures and functions section contains procedures and functions that comprise the internal implementation of the common module. When a common module is a part of some functional subsystem that includes multiple metadata objects, this section can also contain other internal export procedures and functions intended to be called only from other objects of this subsystem.
  
  In large common modules, we recommend that you split this section into subsections based on their functionality. Each subsection is preceded by a comment, which we also recommend formatting using the same approach. Examples: 

For platform version 8.2 or earlier

////////////////////////////////////////////////////////////////////////////////
// Infobase update

For platform version 8.3

#Region InfobaseUpdate
// Procedure and function code
#EndRegion

1.5. The following is the section template for modules of objects, managers, record sets, data processors, reports, and so on. You are free to copy it for use in your modules.

For platform version 8.2 or earlier

////////////////////////////////////////////////////////////////////////////////
// INTERFACE

////////////////////////////////////////////////////////////////////////////////
// EVENT HANDLERS

////////////////////////////////////////////////////////////////////////////////
// INTERNAL PROCEDURES AND FUNCTIONS

For platform version 8.3

#Region Interface
// Procedure and function code
#EndRegion

#Region EventHandlers
// Procedure and function code
#EndRegion

#Region InternalProceduresAndFunctions
// Procedure and function code
#EndRegion

• The Interface section contains export procedures and functions intended for use in form modules, in other configuration modules, or by other programs (for example, via an external connection). This section must not contain export procedures and functions intended for calling from modules of the current object, its forms, or its commands. For example, a procedure that fills a document tabular section and is called from the filling handler in the object module or from a command handler in a document form does not belong to the object module interface (because it is only called from the module itself and from the forms of this object). Add such procedures to the Internal procedures and functions section.
• The Event handlers section contains the event handlers of the object module (OnWrite, Posting, and so on)
• The purpose of the Internal procedures and functions section is the same as in common modules.

1.6. The following is the section template for form modules. You are free to copy it for use in your modules.

For platform version 8.2 or earlier

////////////////////////////////////////////////////////////////////////////////
// FORM EVENT HANDLERS

////////////////////////////////////////////////////////////////////////////////
// FORM HEADER ITEMS EVENT HANDLERS

////////////////////////////////////////////////////////////////////////////////
// FORM TABLE EVENT HANDLERS OF <TABLE NAME> TABLE
//

////////////////////////////////////////////////////////////////////////////////
// FORM COMMAND HANDLERS

////////////////////////////////////////////////////////////////////////////////
// INTERNAL PROCEDURES AND FUNCTIONS

For platform version 8.3

#Region FormEventHandlers
// Procedure and function code
#EndRegion

#Region FormHeaderItemsEventHandler
// Procedure and function code
#EndRegion

#Region FormTableEventHandlersOf<TableName>Table
// Procedure and function code
#EndRegion

#Region FormCommandHandlers
// Procedure and function code
#EndRegion

#Region InternalProceduresAndFunctions
// Procedure and function code
#EndRegion

• The Form event handlers section contains the procedures that are event handlers of the form: OnCreateAtServer, OnOpen, and so on.
• The Form header items event handlers section contains the procedures that are handlers of the items located within the main form area (this includes everything that does not belong to the tables within the form).
• The Form table event handlers of <table name> table sections contain the procedures that are handlers of form tables and table items. An individual section is created for procedures that handle each table.
• The Form command handlers section contains procedures that handle form commands (the procedure name is specified in the Action property of the command).
• The purpose of the Internal procedures and functions section is the same as in common modules.

2. General requirements to program module sections.

2.1. Module header is a comment at the very beginning of a module. A module header contains a brief description of the module and the conditions for its use.

Example:

////////////////////////////////////////////////////////////////////////////////
// General-purpose client procedures and functions for:
// - working with lists in forms;
// - working with the Event Log;
// - handling user actions during the modification of a text that consists
//   of multiple lines, such as a document comment;
// - miscellaneous.
//
////////////////////////////////////////////////////////////////////////////////

We recommend that a header of a form module contains the description of form parameters.

2.2. Variable description section. Name your variables according to the general variable naming rules. For variable usage recommendations, see Using global variables in modules.

For each variable, add a comment that clearly explains its purpose. We recommend that you add the comment to the same line where the variable is declared.
Examples:

Variable AccountingCurrency Export; // Currency used for accounting
Variable SupportAddress Export; // Email address for sending error messages

2.3. Interface. Add export procedures and functions that constitute the interface right after the variable description. These procedures and functions are intended for use by other configuration objects or by other programs (for example, via an external connection), hence they should be easily visible in a module.

See also: Procedure and function descriptions

2.4.1 Event handlers of a form, commands, and form items. In a form module, precede the internal procedures and functions by form event handlers, as well as the event handlers of commands and form items.

2.4.2. For each event, specify a procedure for handling it. If the same actions should be executed when events occur in different form items, do the following:

• create an individual procedure (function) to execute the required actions
• create an individual handler with a default name for each form item
• call the required procedure (function) from each of these handlers

This is an example of incorrect implementation:

&AtClient
Procedure ByPerformerOnChange(Item)
 FilterParameters = New Map();
 FilterParameters.Insert("ByAuthor", ByAuthor);
 FilterParameters.Insert("ByPerformer", ByPerformer);
 SetListFilter(List, FilterParameters);
EndProcedure

&AtClient
Procedure ByAuthorOnChange(Item)
 ByPerformerOnChange(Undefined);
EndProcedure

This is an example of correct implementation:

&AtClient
Procedure ByPerformerOnChange(Item)
 SetFilter();
EndProcedure

&AtClient
Procedure ByAuthorOnChange(Item)
 SetFilter();
EndProcedure

&AtServer
Procedure SetFilter()
 FilterParameters = New Map();
 FilterParameters.Insert("ByAuthor", ByAuthor);
 FilterParameters.Insert("ByPerformer", ByPerformer);
 SetListFilter(List, FilterParameters);
EndProcedure

This requirement is based on the fact that, logically, procedures that are event handlers are not intended to be used in module code and are instead called by the platform itself. And mixing these two scenarios in a single procedure makes its logic unreasonably complicated and reduces its stability (since in this case, procedure code must watch for many kinds of direct calls from the code, instead of a single platform event).

2.5. Event handlers of the object and object manager modules follow the export procedures and functions of the module but precede the internal ones.  

2.6. Internal procedures and functions of the module that are not event handlers and constitute internal module implementation follow event handlers in the module.

When a common module is a part of some functional subsystem that includes multiple metadata objects, this section may also contain other internal export procedures and functions intended for being called only from other objects of this subsystem.

We recommend that you group procedures and functions that are interrelated by their nature or operation logic together. We do not recommend explicit grouping of module procedures and functions into server, client, and no-context blocks because such grouping complicates the understanding of module logic and distracts developers by drawing their attention to implementation details.

2.7. Initialization section contains operators that initialize module variables or an object (form). Example:

SupportAddress = "<a href=""mailto:int@1c.com"">int@1c.com</a>"; // Address to contact support
Initialize();

Module texts

This article describes the standards that apply to module content. All of the listed recommendations are mandatory unless noted otherwise.

1. Write module texts in English (do not use the Russian script variant).

3. Program modules should not contain any blocks of code that are commented out or in any way connected with the development process (debugging code, auxiliary marks) or with the specific developers of this code. Such snippets should be removed after completing debugging or refactoring.

Incorrect:

Procedure BeforeDelete(Cancel)
//    If True Then
//        Message("Debug message");
//    EndIf;
EndProcedure

Also incorrect:

Procedure BeforeDelete(Cancel)
    If True Then
        // Johnson: complete this
    EndIf;
EndProcedure

Correct: after completing debugging or refactoring, remove the BeforeDelete handler from the code.

4. Module text is formatted following the rule that there should be a single operator per line. Multiple operators are only allowed for assignment operators of the same kind:

InitialIndex = 0; Index = 0; Result = 0;

5. Module text should be structured using indented syntax. Tabulation is used to create indents (do not use spaces, so that when the number of characters in the tabulation changes, the text alignment is preserved).

Tabulation size is standard (4 characters).

5.1. Only the following items should begin in the leftmost position:

• operators Procedure, EndProcedure, Function, EndFunction; 
• operators of preliminary declaration of procedures and functions; 
• headers (descriptions) of procedures and functions; 
• declarations of module variables; 
• operators of the "main program section" (taking syntax indent into account);
• &AtClient, &AtServer compilation directives;
• preprocessor instructions, including #Region and #EndRegion.

5.2. Procedures BeginTransaction and CommitTransaction are not considered operator brackets, therefore the text between them is not indented.

6. All lines longer than 120 characters should be wrapped. We recommended that you do not create lines longer than 120 characters except when wrapping them is impossible (e.g. code defines a long string constant that is displayed without carrying over in a message window using UserMessage object).

7.1. Module texts may contain comments. Comments should be clear enough to describe how the module or the operator works. Comment text should follow English language rules, use an appropriate business style, not be emotional and not contain any words that are not related to program functions. 

7.2. Shorter comments are added to the end of the commented string:

ErrorsFound.Columns.Add("Number"); // for compatibility reasons

Longer comments or comments that describe a block of code go before the commented code in an individual line.

7.3. Longer comments should begin with a capital letter and end with a full stop. Text is aligned by the left border of the commented code. A space should separate "//" characters of the comment and the comment text.

// Initializing variables for calculations
// that are performed further in the module.
CurrentDate = CommonUse.GetWorkDate();
CurrentYear = Year(CurrentDate);
CurrentMonth = Month(CurrentDate);
CurrentWeek = WeekOfYear(CurrentDate);
CurrentDay = Day(CurrentDate);

7.4. You can split large procedures and functions into collapsible regions. The region names must comply with the Rules of naming variables standard.

See also

• Common module naming rules
• Module structure

Writing register records

This article describes the standards that apply to the order of writing register records. All of the listed recommendations are mandatory unless noted otherwise.

1. We recommend that you do not use explicit writing of register record sets (with the Write method) in document posting handlers. The writing should be performed implicitly by the platform during the completion of the posting handler execution.

If you ignore this recommendation, parallel document posting by of multiple users might cause deadlocks.

2. Scenarios where data stored in registers is required by algorithms executed before the completion of posing handler execution are an exception to this rule.

See also:

• Document posting requirements
• Self-sufficiency of registers
• Using the Active property of register records