2. Danfoss
  3. PLUS 1® GUIDE

Danfoss PLUS 1® GUIDE User guide

  • Hello! I am an AI chatbot trained to assist you with the Danfoss PLUS 1® GUIDE User guide. I’ve already reviewed the document and can help you find the information you need or explain it in simple terms. Just ask your questions, and providing more details will help me assist you more effectively!
  • What is the significance of the first letter in a file name when coding in Structured Text (ST)?
    When should spaces be added between variable names and operators?
    What are the naming conventions for variables in Structured Text (ST)?
    How should white spaces be used in Structured Text (ST)?
    Is it acceptable to use reserved words in Structured Text (ST)?
    What is the preferred capitalization style for variable names in Structured Text (ST)?
    What is the recommended naming style for files in Structured Text (ST)?
ENGINEERING TOMORROW
User Manual
ST
(Structured Text)
Coding Guidelines
www.powersolutions.danfoss.com
User Manual
ST
(Structured Text) Coding Guidelines
About this Manual
Organization and Headings
To help you quickly find information in this manual, the material is divided into sections,
topics, subtopics, and details, with descriptive headings set in bold type. Chapter or
section titles appear at the top of every page in large bold type.
In the PDF version of this document, clicking an item underlined in blue italic type jumps
you to the referenced page in the document.
Special Text Formatting
Controls and indicators are set in bold black type.
Table of Contents
A Table of Contents (TOC) appears on the next page. In the PDF version of this document,
the TOC entries are hyperlinked.
Revision History
Revison Date Comment Author
001
October 2013
First version
002
October 2013
First revision
003
January 2014
Updated to use Danfoss template, input from SDT added.
004 (AA) January 2014 SDT review input added: Place all PLUS+1 specific guidelines in a
separate chapter
TO
©
2014 Danfoss Power Solutions (US) Company. All rights reserved.
All trademarks in this material are properties of their respective owners.
PLUS+1, GUIDE, and Sauer
-Danfoss are trademarks of Danfoss Power Solutions (US) Company. The Danfoss,
PLUS+1 GUIDE, PLUS+1 Compliant, and Sauer
-Danfoss logotypes are trademarks of Danfoss Power Solutions (US)
Company
.
2
L1415499
·
AA
·
December 2014
User Manual
Structured Text (ST) Coding Guidelines
Contents
Introduction ........................................................................................................................................................... 5
About this Document ................................................................................................................................ 5
Source Files ............................................................................................................................................................ 6
File Naming .................................................................................................................................................... 6
Naming Conventions ......................................................................................................................................... 7
Reserved Words ........................................................................................................................................... 7
Variable Naming .......................................................................................................................................... 7
White Spaces ......................................................................................................................................................... 8
New Lines ....................................................................................................................................................... 9
Indentation .................................................................................................................................................. 12
Line Length .................................................................................................................................................. 12
Comments ............................................................................................................................................................ 13
Data Type Declarations ................................................................................................................................... 14
Derived Type Declaration ....................................................................................................................... 14
Structure Declaration ............................................................................................................................... 14
Enumerated Type Declaration.............................................................................................................. 14
Function Declarations ...................................................................................................................................... 15
Variable Declaration ................................................................................................................................. 15
Statements ................................................................................................................................................... 15
Expressions .................................................................................................................................................. 16
Function Block Declarations .......................................................................................................................... 17
Code Reuse ........................................................................................................................................................... 18
Standard Defined Functions and Function Blocks ....................................................................... 18
User-Defined Functions and Function Blocks ................................................................................ 18
International Code Reuse Considerations ....................................................................................... 18
Safety and Real-Time Concerns in an Embedded Environment...................................................... 19
Error Codes ................................................................................................................................................... 19
Recursion and Stack ................................................................................................................................. 19
Loops .............................................................................................................................................................. 19
Floating Point Data Types ...................................................................................................................... 19
L1415499
·
Rev AA
·
December 2014
3
User Manual
Structured Text (ST) Coding Guidelines
Contents
PLUS+1 GUIDE Specific Guidelines .............................................................................................................20
Tool Specific Notes ....................................................................................................................................20
Standard Defined Functions and Function Blocks .......................................................................20
User-Defined Functions and Function Blocks ................................................................................20
Error Codes ...................................................................................................................................................20
Loops ..............................................................................................................................................................20
Floating Point Data Types ......................................................................................................................20
Pointers and Other Extensions to the Standard ............................................................................20
4
L1415499
·
Rev AA
·
December 2014
User Manual
Structured Text (ST) Coding Guidelines
Introduction
About this Document
This document contains recommended coding guidelines for Structured Text (ST) code in
general, and also in the context of the PLUS+1 GUIDE tool (last chapter only).
L1415499
·
Rev AA
·
December 2014
5
User Manual
Structured Text (ST) Coding Guidelines
Source Files
File Naming
File names should start with a capital letter.
I
f a file name consists of several words then each word should start with a capital letter
(camel case).
Spaces should not be used. Camel case style or underscore style (separating words by the
symbol ‘_’) should be used instead.
Na
ming should be consistent using either camel case or underscore style.
not
Main.xml
EngineControl.xml
Sensor_Driver.xml
Generic_Sensor_Driver.xml
Generic_SensorDriver.xml
6
L1415499
·
Rev AA
·
December 2014
User Manual
Structured Text (ST) Coding Guidelines
Naming Conventions
Names should be speaking, i.e., they should designate the semantics of the named
construct.
Abbreviations are not recommended.
Names should be in upper case for the following constructs:
1. Global variable declarations.
2. Data type declarations.
3. Functions.
4. Function blocks.
Reserved Words
Reserved words should be upper case.
V
ariable Naming
Variable names should have consistent capitalization pattern (either all starting with a
capital letter or none).
not
Boolean variable names should not be negated.
not
TYPE
MODE : BOOL;
END_TYPE
Balance : INT;
Id : INT;
balance : INT;
Id : INT;
IsError : BOOL;
IsNotError : BOOL;
L1415499
·
Rev AA
·
December 2014
7
User Manual
Structured Text (ST) Coding Guidelines
White Spaces
Space should be used before and after binary operator and NOT.
S
pace should be used after ‘,’.
S
paces should be used before and after ‘:’.
S
paces should be used before and after ‘:=’.
W
hite spaces should not be used between unary operator and operand (except NOT).
W
hite spaces should not be used before ‘;’.
W
hite spaces should not be used between function/function block name and its open
parenthesis.
Ok := NOT IsError;
S := -1 + W * H;
S := SUB(1, 2);
VAR_INPUT
A1 : INT;
END_VAR
S := FUNC(IN1 := 1, IN2 := 2);
(* Not correct *)
S := - a;
(* Correct *)
S := -a;
(* Not correct *)
S := -a ;
(* Correct *)
S := -a;
(* Not correct *)
S := ADD (1, 2);
(* Correct *)
S := ADD(1, 2);
8
L1415499
·
Rev AA
·
December 2014
User Manual
Structured Text (ST) Coding Guidelines
White Spaces
White spaces should not be used before ‘,’.
W
hite spaces should not be used before ‘[‘.
W
hite spaces should not be used before ‘)’.
White spaces should not be used after ‘(‘.
Ne
w Lines
New line should be used before each statement.
New
line should be used after ‘;’.
(* Not correct *)
S := ADD(1 , 2);
(* Correct *)
S := ADD(1, 2);
(* Not correct *)
S := ARR [1];
(* Correct *)
S := ARR[1];
(* Not correct *)
S := ADD(1, 2 );
(* Correct *)
S := ADD(1, 2);
(* Not correct *)
S := ADD( 1, 2);
(* Correct *)
S := ADD(1, 2);
(* Not correct *)
S := ADD(1, 2); S:= 3;
(* Correct *)
S := ADD(1, 2);
S := 3;
L1415499
·
Rev AA
·
December 2014
9
User Manual
Structured Text (ST) Coding Guidelines
White Spaces
New
line should be used before and after block comment.
New line should be used before block delimiter keywords (except STRUCT):
1. TYPE END_TYPE
2. VAR END_VAR
3. VAR_INPUT END_VAR
4. VAR_IN_OUT END_VAR
5. VAR_OUTPUT END_VAR
6. VAR_GLOBAL END_VAR
7. VAR_TEMP END_VAR
8. IF END_IF
9. CASE_END_CASE
10. FOR END_FOR
11. WHILE END_WHILE
12. REPEAT END_REPEAT
TYPE
POINT : STRUCT
X : INT := 0;
Y : INT := 0;
END_STRUCT;
END_TYPE
(* Not correct *)
(* Room area
Written by JH.
*)S := H * W;
(* Correct *)
(* Room area
Written by JH.
*)
S := H * W;
VAR
A1 : INT := 100;
END_VAR
10
L1415499
·
Rev AA
·
December 2014
User Manual
Structured Text (ST) Coding Guidelines
White Spaces
For STRUCT type declarations the following applies:
1. There should be a new line after TYPE
2. STRUCT should be written on the same line as the name of the type
3. There should be a new line after STRUCT
4. There should be a new line before END_STRUCT
New line should not be used:
1. Before assignment operator ‘:=’
2. Before function name (in declaration)
3. Before function block name
4. Between VAR/VAR_INPUT/VAR_OUTPUT/VAR_IN_OUT and
CONSTANT/RETAIN/NON_RETAIN
5. Between IF/CASE/WHILE/UNTIL and its expression
6. Between FOR and variable name
TYPE
POINT : STRUCT
X : INT := 0;
Y : INT := 0;
END_STRUCT;
END_TYPE
(* Not correct *)
VAR
CONSTANT SENSOR_ID : INT := 100;
CORRECTION : INT := 100;
END_VAR
(* Correct *)
VAR CONSTANT
SENSOR_ID : INT := 100;
CORRECTION : INT := 100;
END_VAR
L1415499
·
Rev AA
·
December 2014
11
User Manual
Structured Text (ST) Coding Guidelines
White Spaces
Indentation
Indention should contain two (2) spaces.
Each new enter block delimiter keyword adds indentation level for the code inside block.
Each new exit block delimiter keyword should have same indentation as its enter block
delimiter keyword.
Li
ne Length
Line length should not exceed 130 characters.
VAR
BALANCE : INT;
END_VAR
12
L1415499
·
Rev AA
·
December 2014
User Manual
Structured Text (ST) Coding Guidelines
Comments
Use comments to document code.
Block comments should be placed before commented code.
Single line comment should be indented to the same level as the following code.
Trailing comment should comment the code on the same line.
L1415499
·
Rev AA
·
December 2014
13
User Manual
Structured Text (ST) Coding Guidelines
Data Type Declarations
Use data type declarations to define sets of values.
Use data type declarations if the declared type is used at least twice.
Name of a type declaration should be placed on a new line and indentation.
It is recommended to initialize type on the same line as its name.
Derived Type Declaration
Use derived type declarations to define sets of values that are conceptually separated from
other sets of values with the same encoding (base type).
It is not recommended to declare more than 1 type per line.
S
tructure Declaration
Use structure type declarations to define sets of structured values that have conceptually
cohesive elements variables.
Element variables should be initialized if value is known.
It is recommended to declare no more than 1 variable per line.
It is recommended to initialize variable on the same line as its name.
Enumerated Type Declaration
Use enumerated type declarations to define sets of simple values, i.e., no operations on
the set elements other than test of (non-)equivalence.
It is recommended to define enumeration values on the same line as a type name.
TYPE
BALANCE : INT := 7;
END_TYPE
TYPE
POINT : STRUCT
X : INT := 0;
Y : INT := 0;
END_STRUCT;
END_TYPE
TYPE
ENGINE_MODE : (LOW, HIGH) := LOW;
END_TYPE
14
L1415499
·
Rev AA
·
December 2014
User Manual
Structured Text (ST) Coding Guidelines
Function Declarations
Use functions to abstract computations that are used at least twice.
Function return type should be on the same line as function name.
Variable Declaration
See Structure Declaration on page 14
Variables which are not used shouldn’t be declared.
Within each category, it is recommended that variables are ordered, either by their types,
alphabetically, in the order of their usage in the code, or in some other consistent way.
Statements
Functions should have assigned return value.
Output variables should be assigned.
Empty statement lists are not recommended.
A line should contain no more than one statement.
A single blank line should be used to separate code into logically cohesive parts.
A function size of less than 300 lines of code is recommended (otherwise revise the
functional abstraction).
It is recommended to use less than 6 indentation levels (otherwise revise the functional
abstraction).
Explicit type conversion is recommended.
THEN should be on the same line as the IF/ELSIF keywords; the statements in the THEN
and ELSE blocks should be indented one level.
L1415499
·
Rev AA
·
December 2014
15
User Manual
Structured Text (ST) Coding Guidelines
Function Declarations
Expressions
The following expressions should be simple, no complex expressions or function calls are
recommended (otherwise use temporary variables):
1. Call parameter
2. IF expression
3. CASE expression
4. FOR variable assignment expression
5. FOR final value expression
6. WHILE expression
7. REPEAT expression
C
onstant loop and conditional expressions (i.e. always returning TRUE or always returning
FALSE) are not recommended.
(* Not correct *)
IF (A OR B) and (NOT C) XOR (D >= 15) THEN
Result := 0;
ELSE
Result := 1;
END_IF;
(* Correct *)
Z := (A OR B) and (NOT C) XOR (D >= 15);
IF Z THEN
Result := 0;
ELSE
Result := 1;
END_IF;
16
L1415499
·
Rev AA
·
December 2014
User Manual
Structured Text (ST) Coding Guidelines
Function Block Declarations
See Function Declarations on page 15.
L1415499
·
Rev AA
·
December 2014
17
User Manual
Structured Text (ST) Coding Guidelines
Code Reuse
It is recommended to reuse code when possible.
Standard Defined Functions and Function Blocks
The functions and function blocks defined by the standard should be used when
applicable.
User-Defined Functions and Function Blocks
For reusability, it is recommended that common utility functions are collected into
separate files by type of functionality.
Such common utility files can then be reused in multiple projects.
International Code Reuse Considerations
To enable code reuse within international coding teams, or if the code is or will be used
internationally, the following recommendations apply:
• Names of functions and variables should be in English.
• Code comments should be in English.
18
L1415499
·
Rev AA
·
December 2014
User Manual
Structured Text (ST) Coding Guidelines
Safety and Real-Time Concerns in an Embedded
Environment
This section describes coding guidelines that applies to real time control systems.
Error Codes
When calling a function that returns error and/or status parameters, those parameter
should be examined after the call has returned.
Recursion and Stack
Avoid nesting calls too deeply, and make sure that your tests cover the worst-case nesting
depth.
Avoid recursion.
Loops
Avoid using potential endless loop constructs like while and repeat until. Instead prefer
use of the for-loop with a fixed number of iterations.
Floating Point Data Types
Floating point calculations are slower than integer calculations and should be avoided.
L1415499
·
Rev AA
·
December 2014
19
User Manual
Structured Text (ST) Coding Guidelines
PLUS+1® GUIDE Specific Guidelines
Tool Specific Notes
Files will have an XML extension and be stored in PLCopenXML format by the tool. File
types such as *.st and *.exp are supported, but only as import sources to *.xml format. As a
consequence, this document will not describe specific guidelines for these file formats.
PLUS+1 GUIDE supports functions and function blocks to be called from graphical code
only, either directly or indirectly from other program organization units. Therefore this
document will not describe specific guidelines for constructs such as programs,
configurations, tasks and resources.
For compatibility with other tools, PLUS+1 GUIDE supports a number of language
extensions that are technically outside the language definition. Using these extensions will
let the code compile, but with warnings.
Standard Defined Functions and Function Blocks
In PLUS+1 GUIDE, the standard functions and function blocks are available from the “Code
Blocks” trees on the right-hand side of the editor.
User-Defined Functions and Function Blocks
User defined functions and function blocks are available from the “Code Blocks” trees in
PLUS+1 GUIDE.
Error Codes
PLUS+1 GUIDE defines a number of runtime error codes that can be obtained by calling
the built-in function GET_CURRENT_RUNTIME_ERROR_FLAGS().
This should be done after calling functionality that might lead to any of the error flags to
be set.
These runtime error codes are described in the GUIDE manual.
Loops
PLUS+1 GUIDE generated code will terminate while- and repeat until-loops that take too
long to execute during runtime.
(Use GET_CURRENT_RUNTIME_ERROR_FLAGS() after such loops to find out if this has
happened.)
Floating Point Data Types
Note that some PLUS+1 hardware units, such as MCxx-xx, do not fully support the LREAL
type.
Pointers and Other Extensions to the Standard
Pointers and other extensions to the standard are included in PLUS+1 GUIDE only for
compatibility with other tools, and should be avoided in new code.
In old imported code it is recommended that such code is rewritten.
20
L1415499
·
Rev AA
·
December 2014
Page is loading ...
Page is loading ...
/