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).
This recommendation is optional
2. Program modules should not contain any unused procedures or functions.
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.
Procedure BeforeDelete(Cancel) // If True Then // Message("Debug message"); // EndIf; EndProcedure
If True Then
// Johnson: complete this
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.