Module structure

This article describes the standards that apply to the 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.

This recommendation is optional We recommend that you group handlers of a single form item together, and order them within these groups according to their order in the properties panel of the form editor in Designer.

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.  

This recommendation is optional We recommend that you arrange handlers based on their order in the 1C:Enterprise script description.

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 a 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. The 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();

Next page: Module texts