Rules of Code Designing

Article number: KB000005

General Information

Related blocks:

• Fore

Description

Below are recommendations on designing the source code of application systems in Foresight Analytics Platform. Coding style is supported automatically by the platform editor when the Format Code Automatically option is enabled in the development environment settings.

Principles of Naming

• Identifiers of classes and interfaces, their fields and methods, of functions and their parameters, variables and custom types, as well as enumeration types' constants are to consist of one or more English words and reflect functionality of the identifier.

• The words that make up an identifier should start with upper case letters, the other letters are displayed in lower case. An identifier cannot contain underscore characters. See examples of correct identifiers: Cube, CubeDimension, GoodCasedIdentifier.

• When using two-letter abbreviations in an identifier, you should use uppercase letters, otherwise (an abbreviation consisting of three or more characters) the first letter should be in upper case while the others should be in lower case (UI, IO, Xml, Dom).

• Using abbreviations in identifiers is allowed in the following cases:

• • To shorten long words (with 7 letters or more).

  • To name local variables and function parameters, private fields of classes.

• Using one-letter identifiers to name local variables is allowed. The letter should be in upper case. It is recommended to use one-letter identifiers I, J, K, and so on to name variables that count the cycles.

• The following prefixes and suffixes should be used: the prefix "I" for names of interfaces, the prefix "F" for names of class fields, the suffix Exception for names of exception classes. Using prefixes and suffixes for other purposes is not allowed.

• When creating identifiers for methods and functions, first, specify the operation, next specify the adjectives and only after that specify the objects. For example: CreateValidNamedObjects and not ValidNamedObjectsCreate; ShowModal and not ModalShow. Using adjectives and objects in identifiers is desirable but not necessary.

Code Formatting

Tab and space characters should be used for code formatting. Tab character should be used to make indents while the space character is to separate lexemes in code.

Indents

Indents (single tab characters) should be used in the following cases:

• In the block of variables description. The strings that directly describe variables should be positioned under the line containing the Var operator and to have an indent:

Var
    I: Integer;

• In multi-line expressions, in descriptions of parameters and functions that take more than one line:

Function Calculate(FirstParameter,
    SecondParameter: Integer; Var ThirdParameter: Integer);
    
ThirdParameter := FirstParameter +
    SecondParameter * FirstParameter;

• In descriptions of procedures and functions. The code between Begin and End operators should be indented:

Function ConvertValue(Value: Variant): Integer;
Begin
    Alfa := 1;
End;

• In descriptions of classes and enumerated types:

Class ConfirmForm: Form;
    OkButton: Button;
End Class;

Enum Colors;
    Red,
    Green,
    Blue
End Enum Colors;

• In switches. First, each option should be indented. Second, the code describing each option should start in the next line and be indented relative to the line with the Case/Else operator:

Select Case Value
    Case 0:
        Alfa := 1;
        Beta := 2;
    Else
        Gamma := 3;
End Select;

• In a conditional statement:

If Value = 0 Then
    Alfa := 1;
Else
    Beta := 2;
End If;

• In cycle statements:

For I := 0 To Count - 1 Do
    Alfa := 1;
End For

For Each V In List Do
    Debug.WriteLine(V);
End For;

While I < Count Do
    Alfa := 1;
End While

Repeat
    Alfa := 1;
    I := I + 1;
Until I = Count;

• In exception handlers:

Try
    Alfa := 1;
Except
    Beta := 2;
Finally
    Gamma := 3;
End Try;

Using indents in other cases is not allowed.

Spaces

Spaces should be used to separate lexemes in source code. Several consecutive spaces between lexemes should be replaced with one space character.

Spaces should be used to separate lexemes in the following cases:

• Before and after keywords of the language.

• Before and after assignment operator in assignment statements.

• Before and after operators in expressions.

• After commas in parameters when describing and calling functions as well as in other enumerations of elements.

• After question mark, before and after colon in operation of selection.

• After the colon in descriptions of variables, properties and parameters of functions.

Spaces should not be used to separate lexemes in the following cases:

• Before a semicolon.

• After opening and before closing round bracket.

• Before commas in parameters when describing and calling functions, as well as in other enumerations.

• Before colons in descriptions of variables, properties and parameters of functions.

Empty Lines

An empty line should be used in the following cases:

• To separate declarations of classes and types from each other.

• To separate implementations of functions and methods from each other.

Other

Statements from one language construct (Begin – End, Repeat – Until, Try – Except – Finally – End Try, Select – End Select, and others) must be in one position in the string (in one column).

Example

Enum WhatICanDo
    GetSomeSleep,
    BrowseInternet,
    PlayFavouriteGame
End Enum WhatICanDo;

// Demo class
Class GOODFORMATForm: Form
    PlayGame: Button;
    CancelButton: Button;
    BrowseInet: Button;
    SomeSleep: Button;

    Sub CancelButtonOnClick(Sender: Object);
    Begin
        Self.Close;
    End Sub CancelButtonOnClick;

    Sub Sleep(Millisecs: Integer);
    Var
        J, I: Integer;
    Begin
        I := (Millisecs + 999) Div 1000;
        While I > 0 Do
            For J := 0 To 999 Do
                If Millisecs > 0 Then
                    Millisecs := Millisecs - 1;
                Else
                    I := 0;
                    Break;
                End If;
            End For;
            I := I - 1;
        End While;
    End Sub Sleep;

    Sub ShellExecute(Command: String);
    Begin
        Repeat
            Command := Command + " ";
        Until Command.Length > 100;
    End Sub ShellExecute;

    Function CreateProcess(ProcessName: String): Boolean;
    Var
        Result: Boolean;
    Begin
        Result := True;
        Try
            WinApplication.NotImplementedBox;
            Raise New Exception.Create("This function is not yet implemented");
        Except
            Result := False;
            WinApplication.InformationBox(
                "Execution error in  GOODFORMATForm.CreateProcess");
        End Try;
        Return Result;
    End Function CreateProcess;

    Sub HaveFun(Action: WhatICanDo);
    Begin
        Select Case Action
            Case WhatICanDo.GetSomeSleep:
                Sleep(60000 * 30);
            Case WhatICanDo.BrowseInternet:
                ShellExecute("http://www.favouritesite.com");
            Case WhatICanDo.PlayFavouriteGame:
                CreateProcess("C:\Quake3\Quake3.exe");
            Else
                WinApplication.InformationBox("Nothing to do!");
        End Select;
    End Sub HaveFun;

    Sub PlayGameOnClick(Sender: Object);
    Begin
        HaveFun(WhatICanDo.PlayFavouriteGame);
    End Sub PlayGameOnClick;

    Sub BrowseInetOnClick(Sender: Object);
    Begin
        HaveFun(WhatICanDo.BrowseInternet);
    End Sub BrowseInetOnClick;

    Sub SomeSleepOnClick(Sender: Object);
    Begin
        HaveFun(WhatICanDo.GetSomeSleep);
    End Sub SomeSleepOnClick;

End Class GOODFORMATForm;