Formatting Structured Text and Extended Structured Text (ExST)

Table of Contents
Indentations
Column limit
Line limit
One statement per line
Braces
Line-Wrapping
- Where to set the line break
- Line-Wrapping examples
Whitespace

Indentations

For indentation use tabs (ASCII 0x09) only with 4 spaces width.

Column limit

Our column limit is 120 characters. When code that would otherwise be on a single line is longer than 120 characters, the code must be split multiple lines, this is called line-wrapping.

Line limit

The recommendation for functions, methods, programs, properties, actions, transition objects and function block bodies is that the lines of code are less than 35. Anyway a hard rule on number of lines is not helpful, especially on drivers. It sometimes makes no sense to cut it off on line number xy because you need more to get a coherent piece for it. More important is that you eliminate duplications of code and that the code is testable. Anyway, small is good, so beware of MEGAMOTHs (MEGA MOnolithic meTHod) and god objects!

One statement per line

Each statement is followed by a line break.

Braces

Braces must be used also when these are optional here are some examples: fooBarBaz := ((foo * bar) + baz);, IF (foo) THEN or foo := (foo AND (NOT bar)). It cannot be assumed that every reader knows the operator precedence.
For multi-line expressions, we indent once after the opening brace, outdent again with the closing brake.
Line breaks before the opening brace are prohibited.
For multi-line expressions, there must be a line break after the opening brace. If there is more than one opening brace in a row where the closing braces are in another line, then the line break comes after the last opening brace in this row. The number of indentations results from the number of opening braces.
For multi-line expressions, there must be a line break before the closing brace.
Only when a closing brake terminates an expression is a line break after the closing brace allowed and required.

Line-Wrapping

Line-wrapping must be used if the expression doesn’t fit to the column limit.
Line-wrapping must be used for multi assignment. For line wrapping on multi assignment, it is required to indent once after the first assignment, and it must be outdented with the value. The value and the semicolon is at single outdented line.
Line-wrapping is allowed to improve readability, even if the expression would fit into the column limit. There is no rule when to do this, it’s the decision of the developer.
For line breaks the operator is placed at the beginning, and not at the end of the line, except the assignment operator: it has to be at the end of the line.
For each opening brace ([{ is one indent required and for each closing brace )]} is one outdent required.
For line-wrapping without braces for example a multi assignment, is it required to indent once after the first line, and outdent with semicolon, respectively with the end of the expression.
For multi-line calls the comma (parameter separator) is placed at the end of the line.

Where to set the line break

For the assignment operator the line break is to be set afterward.
For all non-assignment operators, put the line break before it.
For the dot separator ., put the line break before it.
For the colon :, put the line break before it at declarations, and for labels/cases put the line break afterward.
Opening braces ([{ stays attached to the symbol that precedes it.
For the closing braces )]}, put the line break before it.
The comma separator , stays attached to the symbol that precedes it.

Line-Wrapping examples

Often it is better for the readability to declare local objects/variables or extract methods to avoid line-wrapping

line-wrapping call

fooTimer(	
	IN:=TRUE,
	PT:=T#100MS,
	Q=>foo,
	ET=>fooActive
);

nested line-wrapping call

fooTimer(	
	IN:=THIS^.doFooHooAndGetState(
		foo := foo,
		bar := bar,
		baz := baz
	),
	PT:=T#100MS,
	Q=>foo,
	ET=>fooActive
);

line-wrapping single assignment

fooBarBaz	:= (
	foo
	AND bar
	AND baz
);

line-wrapping nested single assignment

fooBarBaz := ((
		(foo) AND (bar) AND (baz)
	) OR (
		(foo) AND (barBaz)
	) OR (
		(fooBar) AND (baz)
	)
);

line-wrapping multi dimensional array declaration and initialization (preferred style)

fooBar :ARRAY [
	FIRST_FOO .. LAST_FOO
] OF ARRAY [
	FIRST_BAR .. LAST_BAR
] OF STRING := [
	['foo', 'bar'],
	['baz', 'foo Manchu']
];

line-wrapping multi dimensional array declaration and initialization (not favored style)

shelf	:ARRAY[
	FIRST_LEVEL..LAST_LEVEL,
	FIRST_SPACE_AT_LEVEL..LAST_SPACE_AT_LEVEL
] OF STRING := [
	'foo',
	'bar',
	'baz',
	'foo Manchu'
];

If it is not necessary (e.g. as a parameter of an existing method/function), it is recommended to use an array of arrays.

line-wrapping structured type declaration and initialization

X_AXIS_PARAMS		:PosControlledBeckhoffDriveParameter	:= (
	velocity				:= 100.0,
	jogVelocity				:= 10.0,	
	acceleration			:= 600.0,
	decceleration			:= 600.0,
	referencePosition		:= 0.0,
	torquelimitBraketest	:= 0,
	settlingAccuracy		:= 0.2
);

line-wrapping structured type array declaration and initialization

locationPositions	:ARRAY[GVL_Config.FIRST_TEACHPOINT..GVL_Config.LAST_TEACHPOINT] OF LocationPosition	:= [
	(*loading	station; LocationTeachPoints.loadingStation*)
	(posX := 781.85,	posY :=	32,		posZ :=	130,	strokeZ	:= 65,	prePosOffsetY := 0,		locationType :=	LocationTypes.withShutter),
	(*xrd	orienter;	LocationTeachPoints.xrdOrienter*)
	(posX := 922,		posY :=	1239,	posZ := 200,	strokeZ := 45,	prePosOffsetY := 0,		locationType :=	LocationTypes.withShutter),
	(*oven 1;	LocationTeachPoints.oven1*)
	(posX := 919.5,		posY :=	3173.5,	posZ :=	1026,	strokeZ	:= 61,	prePosOffsetY := 112.5,	locationType := LocationTypes.withShutter),
	(*oven 2;	LocationTeachPoints.oven2*)
	(posX := 920.3,		posY :=	4047,	posZ :=	1022,	strokeZ	:= 65,	prePosOffsetY := 112.5, locationType := LocationTypes.withShutter)
];

line-wrapping fluent method call

THIS^.xAxis
	.setVelocity(LIMIT(MINIMAL_VELOCITY, PcInterface.axes[AxesIds.xAxis].setSpeed , Config.X_AXIS_PARAMS.velocity))
	.setPosition(THIS^.locationPositions[THIS^.transportSystemPcInterface.curLocation].posx)
.startAbsolute(TRUE);

line-wrapping if statement

IF ((
		(foo) AND (bar) AND (baz)
	) OR (
		(foo) AND (barBaz)
	) OR (
		(fooBar) AND (baz)
	)			
) THEN
	;
END_IF

line-wrapping foo loop

FOR (
	foo := THIS^.fooList.getFirstFooIndex()
) TO (
	(THIS^.fooList.getNumberFoos() - FOO_STEP_WIDTH)
) BY (
	FOO_STEP_WIDTH
) DO
	;
END_FOR;

here is it be easier and more readable to declare local variables and use this at the loop

Whitespace

Vertical whitespace

Multiple consecutive blank lines are prohibited.
For line-wrapped expressions, a single blank line afterward is required, except on if-statement and loop conditions.
The last line of a class, method, function, property, program, or declaration must be a single blank line. This is necessary for the readability of the xml files if a merge conflict occurs.
Single blank lines are there to improve the readability, they should show logical subsections of the code. There is no exact rule when a blank-line should appear (except the rules above). Where to set blank lines is at the developer’s discretion.
For JMP labels, there is no space between label and :, but always a line break after the :.
For CASE-statement labels, there is no space between label and :. Normally, there is a line break after the :, but there is one exception: if all cases contain a single line statement, then it’s permitted to put it in one line, and the line break is after the semicolon, but then there must be minimal one tab (ASCII 0x09) after the :.
For single line if statements, there is never ever a line break before the THEN-keyword, so it must look like IF (foo) THEN.
Block comments require s a line break after the opening sequence (*, and before the closing sequence *).

Horizontal whitespace

Keywords such as IF, ELSIF, WHILE etc. must be separated with one space (ASCII 0x20) from their braces that follow them on the line.
For a single line variable declaration, the colon must be separated from the variable with at least one tab (ASCII 0x09), but there is no space between the colon and datatype. When the variable is initialized, the assignment-operator must be separated from the datatype by at least one tab.
Operators must always be separated from their operands with a single space (ASCII 0x20) if they are on the same line. For the case of horizontal alignment, the operators must be separated with at least one tab (ASCII 0x09) from their operands.

Horizontal alignment

Horizontal line alignment is not required, but also not prohibited.
Horizontal alignment is good for readability, but it’s bad for the maintenance of the code. Its usage is at the developer’s discretion.

Comments

Comments must always be above the line you are commenting on, there must not be a blank line between the comment and what is being commented on. Pragmas are between the comment and the commenting line.
Commented out program code is not allowed. It's okay to test something, but it needs to be cleared before you commit the code.
Comments have the same indentation as the line you are commenting on.
Multi line comments must always be block comments.
For block comments at declarations and header (except for reStucturedText comments), it’s not allowed to use designs like frames because they destroy the mouse overview.

Inhalte