Code layout

Readable code starts with a consistent layout of the code. In this section the layout rules for code at Charta Software are described.

The rules for laying out code are described in the following subsections.

Indentation

Code is indented to allow the reader to clearly see the flow of control. The used indentation level is 2 spaces without using tab characters. In general the contents of a block is indented. A block can be delimited by different constructs:

The contents of flow control statement like if, while and try:

if Condition then
  TrueStatement
else
  FalseStatement;

The contents of a declaration section like var, const and type:
```
var
  Variable1: TInteger32;
  Variable2: TInteger32;
```

The parameters of a long function call:

FunctionA(
  Parameter1,
  Parameter2,
  Parameter3
);

Finally, the begin and end keyword are not indented together with the blocks they delimit:

while Condition do
begin
  Statement1;
  Statement2;
end;

New lines

One statement per line

Every statement uses at least one line of code. This means that no two statements may share a line. Also, the keywords delimiting structured constructs cannot share a line with the parts that make up the contents of those constructs. More precisely, the following constructs always are located on their own line of code:

The block statement keywords begin and end.
The declaration statement keywords like type, const and var.
Every declaration that occurs within a declaration statement.
The keyword uses
Every unit reference that occurs in a uses list.
The visibility specifiers private, protected and public

Statements using more than one line

The fact that every statement uses at least one line of code also means that some statements use more than one line. The flow control statements all use more than one line because the statements they contain are always located after the line with the introductory keyword (and condition).

Function calls also can be distributed across multiple lines. Whenever a function call grows too large to be fit on a reasonably wide screen one can decide to split the call into multiple lines. When a function call is split, every parameter to the function should be placed on its own line with the proper indentation. This means that no parameter may share the line with an other parameter and that either all parameters are on the same line or every parameter is on its own line.

When a construct uses more than one line empty lines are added before and after the construct to further enhance readability. These lines are always added except in the following cases:

When a construct is the first in the list of nested constructs the leading empty line is dropped.
When a construct is the last in the list of nested constructs the trailing empty line is dropped.

Grouping statements

Multiple statements can be grouped by applying the rules for adding empty lines to multi-line statements to a group of statements. Grouping statements this way can make the structure of code more clear. Statements should be grouped when the following conditions are met:

Each individual statement in the group occupies only one line.
All statements in the group are either assignments or function calls or start with the exact same expression.
The resulting group does not contain another group.
If not grouping the statements results in a series of groups each consisting of a single statement.

Alignment on delimiters

Alignment of assignments

Assignment statements can be aligned on the assignment sign (:=) by placing all the assignment signs in the same column that starts one space after the longest left-hand side. Assignment statements should be aligned if both of the following conditions are met:

The assignments are part of the same statement group.
The left-hand sides of the assignment statements share the same complexity. The occurrence of the dot operator increases the complexity of the left-hand side.

Please note that these rules mean that assignments should not be aligned when assignment blocks are separated using an empty line and that statement grouping takes precedence over assignment alignment.

Alignment of declarations

Variable declarations within the same declaration section should be aligned on the colon (:). The colon should be placed right after the identifier and all the types should be in the same column that starts one space after the colon that is placed after the longest identifier.