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:


Comments
0
Add comment