PLC programs development guidelines

Itris Automation Square

January 20th 2012 - Version 1.6.7
http://www.automationsquare.com
PLC programs development guidelines
2/19 January 20th 2012 - Version 1.6.7
Contents
1 Document purpose 5
2 Document structure 6
2.1 Rules classication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.2 Presentation of each rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3 Coding Rules 7
3.1 Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.1.1 PLCs common Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.2.1 PLCs common Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.3 Writing code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.3.1 PLCs common Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.3.2 Unity Pro specic rules (Schneider Electric). . . . . . . . . . . . . . . . . . . . . . . . . 10
3.4 Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.4.1 PLCs common Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.5 Useful Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.5.1 Useful information for all PLCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.6 Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.6.1 Unity Project Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4 Annexes 17
4.1 Summary of Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.2 Document history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3/19
PLC programs development guidelines
4/19 January 20th 2012 - Version 1.6.7
Chapter 1
Document purpose
This document contains coding style guidelines for PLC programming, to improve readability, maintainability and
the consistency of PLC programs. It describes simple rules which allow to get meaninful quality indicators from
the rst day of development.
All rules in this document are checked automatically with PLC Checker, which supports PL7 PRO and Unity
Pro from Schneider Electric, STEP7 from Siemens and Rockwell Automation RSLogix 5000 PLCs.
This document was written by IAS seasoned consultants, based on analysis results of many codes used by
Itris Automation Squares customers in several industries and using various ranges of PLCs. It also reects some
best practices from other computer engineering domains such as embedded systems, which have been applying
standard sets of programming guidelines for years.
5/19
Chapter 2
Document structure
2.1 Rules classication
The rules described in this document are classied into several categories: Naming, Comments, Writing and Struc-
ture. The last part of this document also provides useful information which are not only about coding rules, but also
allow improvements of the programs quality. The last part is about the rules on the options of the PLC workbench.
Each category is divided into two parts:
1) The rules that may be applied independently of the PLC for which the program is developed.
2) The rules that are only relevant for a specic PLC or that need to be adapted in order to be applicable.
2.2 Presentation of each rule
The rules are numbered according to their implementation in PLC Checker. For each rule, we nd an identical
structure made up of a title, an explanation of the rule, a justication of its importance and, when relevant, a code
example to facilitate understanding of the rule.
6/19
Chapter 3
Coding Rules
3.1 Naming
The elements manipulated in PLCs have mnemonics. Elements are, for example, variables, routines (sections,
subroutines, FCs . . . ) or function blocks (FB). The purpose of this section is to make sure that the symbols follow
rules ensuring readability, maintainability and allow for greater code perenity. Generally, the libraries elements are
excluded from naming verication. Of course, when the workbench allows this, we dont recommend to change
the elements names dened in the libraries.
3.1.1 PLCs common Rules
N.1 - All program elements should have a mnemonic
All programs elements should have a mnemonic (program, modules, variables, DFB, FB, OB, SR, routine, Add-
On)..
Comment : When all programs elements have a mnemonic, maintenance is easier and it is easier to understand
program content. Moreover, not using mnemonic makes an implicit link between a code and an hardware imple-
mentation.
N.2 - Elements names length should be in a given range
The names of program elements must contain at least 3 characters and no more than 15 characters.
Comment : A minimum number of characters ensures more meaningful naming. A maximum number of
characters allows:
In Schneider Unity, Schneider PL7pro and Rockwell RSLogix : to avoid the mnemonics being truncated in
display or export, . . .
In Siemens Step7: to improve readability
N.3 - Topological physical address should not be used as part of a mnemonic
The mnemonics shall not contain a reference to their physical address (for instance, MW2, FB4. . . ).
Comment : The reference to the physical address of the entity in the code may have bad properties : read-
ability is worse, and it may induce dangerous confusion. It should be noted that with the evolution of software
workbenches, referencing the elements names by their physical address is not necessary anymore. Eventhough
such a reference to the physical address may be unintentional, it is prohibited.
Example :
7/19
PLC programs development guidelines
Physical ad-
dress
Mmnemonics comment
%MW23 Cde 23 Never link the naming of the variable to its physical address
N.4 - Debug mnemonics should not be part of the nal program
Some mnemonics (test, toto, titi, tata, tutu, to delete , todo,. . . ) are forbidden, and the comments should not con-
tain debug expressions (like: to do later, to delete, todo)
Comment : Leave debug items in the nal program reduces its readability and may have different behavior
than expected. The list of prohibited elements is congurable (of course, it is language specic).
N.5 - Special or graphical characters are prohibited in mnemonics
The special characters set (e.g : ` a, e, c. . . ), space and accents are prohibited in the mnemonics names. Only al-
phanumerical characters and the underscore are allowed.
Comment : Using special characters, may generate some problems of portability to future workbench version
and / or to other platforms. It also reduces the readability in an international context. Finally, the restriction to only
alphanumerical characters ensures a better distinction between variable names.
Example :
depart := true;
# .... Lines of code
depart := false; #Using the special charactere, leads to a confusion between mnemonics.
N.6 - The programming language keywords should not be used as mnemonics
Programming language keywords (for example if, set, start. . . ) should not be used as mnemonics. But it is
possible that mnemonics contain a keyword. Most cases are handled by PLC workbench, but there are exceptions.
Comment : Using keywords as mnemonics lowers program readability and portability.
Example :
start := true; # mistaken mnemonic, "start" is a language keyword
start_motor := true; # Correct mnemonic
3.2 Comments
In addition to good naming practices, it is important to follow rules when commenting programs. In fact, the more
explicit and detailed the comments are, the more the code will be understandable. Generally, the standard library
elements comments are not checked.
8/19 January 20th 2012 - Version 1.6.7
PLC programs development guidelines
3.2.1 PLCs common Rules
C.1 - All program elements should have a comment
All program elements must be commented (Program, Section, Modules, Variables, DFB, FB, OB, SR).
Comment : If all the program elements are commented signicantly, it is easier to read and understand the
program, therefore its maintenance is less costly.
C.2 - Comments should be longer than a given number of characters
The comments of program elements must contain a minimum number of characters (7 for variables, 15 for codes)
to avoid insignicant comments.
Comment : Having a minimum length ensures that the comments are more meaningful.
C.3 - Each network should have a comment
The networks must be commented. This rule is specic to some languages of the IEC61131 standard. Also please
note that the concept of network is not always present in PLC vendor IDEs.
Comment : In addition to a good overall rate of comments, its important to ensure that comments are well
distributed within the program. Such a rule is also a guide that ensures consistency when copy/pasting code sec-
tions.
C.4 - Comments should not contain comment start marker
Comments should not contain comment start marker (e.g, / *, ( *).
Comment : The presence of a comment start marker is often a symptom of a forgotten comment end marker,
which can lead to commenting out of a part of program and thus a non intended behavior.
Example:
/* Any comment with the end marker has been forgotten
Critical_section_that_must_be_executed_which_is_found_in_the comment();
/* <- The start marker comment is commented because the end marker of the previous comment has been
forgotten */
3.3 Writing code
3.3.1 PLCs common Rules
E.1 - All variables should be written before being read
Except for physical and communication inputs and system variables, all variables should be written before being
read during a PLC cycle.
Comment : a variable that is read before being written, can increase program latency. Efcient code should
respect during one PLC cycle the following diagram:
inputs reading -> processing -> update the outputs.
January 20th 2012 - Version 1.6.7 9/19
PLC programs development guidelines
In addition, make sure that the variables that are never written in the code have been initialized, otherwise they are
updated by other ways.
In some cases it is justied to ignore this rule:
variables that were initialized in the database,
variables updated by a communications link,
state variables that store the value of a previous PLC cycle.
Example:
if urgentAlarme then
alarmeTreatement();
end if;
# ...
urgentAlarme := presenceDefault AND ...;
In this example, the call of the alarm function alarmTraitement happens during the next PLC cycle, which
increases the average response time. This delay is around one PLC cycle.
E.2 - The parameters of the user functional blocks should be used correctly
This rule is divided into three sub-rules :
E.2.a and b - Inputs of the user functional blocks should be read and not written.
E.2.c and d - Inputs/Outputs of the user functional blocks should be read and written.
E.2.e - Outputs of the user functional blocks should be written before being read.
Comment : Parameters incorrectly used are evidence of unnished code or a code that still contains unnecessary
elements of correct behavior. In some PLCs, misusing parameters may generate undesirable and potentially dan-
gerous effects, such as data corruption. Please note that checking whether private parameters of user blocks are
used is done by the rule S7.
3.3.2 Unity Pro specic rules (Schneider Electric).
E.U.1 - The functions of the Unity obsolete libraries should not be used
In a new Unity Pro PLC Project, the functions of the obsolete libraries should not be used.
Comment : In Unity, some libraries are obsolete and exist to ensure backward compatibility with previous
versions of Schneider PLCs. In new applications, the usage of the functions of those libraries must be avoided for
future portability problems. Furthermore, some of those functions can make the code nondeterministic (ex: shifts
on signed integers shl int, shlz int, shr int, shrz int, rol int, ror int).
10/19 January 20th 2012 - Version 1.6.7
PLC programs development guidelines
3.4 Structure
3.4.1 PLCs common Rules
S.1 - Backward jumps are forbidden
Backward jumps are forbidden.
Comment : Using a backward jump can trigger an innite loop, which can lead to a PLC shutdown. Moreover,
in general, jumps make the code less understandable and therefore their maintenance is more complex.
Example: Example of jump which triggers an innite loop
Figure 3.1: Example of jump which triggers an innite loop
S.2 - A variable should be elaborated only in one routine
A variable should be elaborated only in one routine.
Comment : A simple and clear code architecture facilitates understanding of the code and therefore its main-
tenance. Moreover, multiple variable elaborations can lead to erratic behavior of the code.
S.3 - A variable should be written from one task only
A variable should be written from one task only.
Comment : writing a variable from several tasks leads to an nondeterministic behavior, such as a potential
access conict.
S.4 - A physical output should be written only once per PLC cycle
A physical output should be written only once per PLC cycle.
Comment : Multiple output writing may lead to problems of dependability. Also, a code where the outputs
are written more than once is less easy to understand and maintain. It should be noted that writing in a loop is
considered as multiple writing and therefore constitutes a violation of this rule.
Example:
January 20th 2012 - Version 1.6.7 11/19
PLC programs development guidelines
if very_complicated_condition then
Critical_Output := TRUE;
end if;
#.... much later in the program
if another_very_complicated_condition then
Critical_Output := FALSE;
end if;
In the case where the output is not controlled where it should be, it is very difcult to identify which affectation is
executed
S.5 - Variables should not be localized
Variable memory mapping should be reserved to variables which elaboration or consumption is done out of the
program : communication tags, I/O variables, special function variables. All internal variables should not be
localized.
Detailed explanation : Using localized variables constraints program evolutivity, due to a more rigid memory
organization. It reduces portability, as memory organization varies from one PLC to another. So the code cannot
be reused in another application, as in the other application the given memory zone may be reserved for other
purposes. Moreover, it may lead to memory organization mistakes in which several variables will be saved in the
same memory cells. This bug may be silent during a long time and be encountered late in the development or in
the production cycle.
S.6 - DFB/FBs instances should be called only once
Comment : A functional block instance owns its variables used to save the FB state between two consecutive
cycles. Each FB execution should modify those variables to show the state evolution. When executed more than
once, it looks like the cycle is progressing twice quicker than the other instances.
Often used more than once, the same instance is the result of a cut and paste not updated.
It may lead to bugs hard to discover.
S.7 - Declared variables should be used
Variables and dened types should be used, except for reserve variables. Reserve variables shall not be used.
Comment : Variables (except reserves) and unused types are often a sign of a forgotten treatment or incomplete
database cleaning. When reserve variables are used this is often the sign of a forgotten renaming.
S.8 - Variables location shall not overlap
The overlapping variables are to be checked.
Comment : Localized variables that overlap are equivalent to an implicit transfer of value between each other.
This is sometimes a difculty to code readability. It is also sometimes a localization error.
S.9 - Complexity measure
Complexity of the code shall be assessed. Loops (for, repeat, while), jumps and a high level of imbrication are
criteria of code complexity.
Comment : Parts of program are more complicated than others. This is specially the case when execution
sequential ow is often cut. This rule searches for some root causes for ow discontinuation, like loops, backward
goto and high complex instructions nested level.
12/19 January 20th 2012 - Version 1.6.7
PLC programs development guidelines
S.10 - SCADA Limitations
SCADA software doesnt support structures arrays. Such constructions shall be avoided for portability purposes.
Comment : When using a SCADA which doesnt support array of structures, it is important to not build a PLC
database based on these arrays of structures. This rule is used here to detect this kind of construction.
3.5 Useful Information
3.5.1 Useful information for all PLCs
I.1 - Comments rate
It is recommended that the code contains a minimum percentage of comments.
Comment : Itris Automation Square recommends a rate of 30% (# of commented instructions / total # of
instructions). Such a minimum rate of comments ensures that the development was carried taking into account the
maintainability of the code, and ensuring that it will be easy to understand when evolution is needed.
I.2 - Code in the comments
It is very important to check the possible presence of code as comments.
Comment : Commenting out code is a typical test and debug strategy. The nal program should not contain
commented out code as maintenance technicians may be confused.
I.3 - Dead code
Provision shall be made against the presence of dead code in the program. \ \
Clarication : Dead code affects the readability and maintainability of the program and can be a symptom of a
functional problem. Please note that when PLC Checker detects unreferenced functions and parts of isolated code
after an unconditional jump, the completeness of the detection is not guaranteed (for example, dead code related
to the evaluation of an expression).
I.4 - List of locked elements
The locked elements are not scanned by PLC Checker, they should be identied for manual review.
Comment : In applications where the major part of the code is locked, it is important to know it.
I.5 - Cyclomatic number v(G)
A cyclomatic number gives information about complexity. It is important to keep it reasonably low.
Comment : A cyclomatic number counts the number of different paths that can be executed in a routine. The
higher this number is, the more difcult it is to validate the correct behavior of the routine. In such a case, the
routine should be divided in subroutines. Each of them having a cyclomatic number below the given threshold.
I.6 - Essential Complexity ev(G)
Essential complexity gives information about unstructured instructions. It is important to keep it reasonably very
low.
Comment : Essential complexity counts the number of different unstructured instructions in a routine. The
higher this number is, the more difcult it is to validate the correct behavior of the routine. Most of the time,
unstructured instructions can normally be replaced by structured instructions.
January 20th 2012 - Version 1.6.7 13/19
PLC programs development guidelines
I7 - Source Line of Code count
The source line of code counts number of instructions in a POU. It is important to keep it under control.
Comment : Very big procedure or function blocks may be difcult to test, to read and to maintain. It may be
better to split a very big procedure into two or more procedures of reasonable size.
I8 - Sequential Function Chart (SFC) steps count
This is the count of steps in a given SFC.
Comment : This rules returns the number of steps found by SFC. This number may be further used to detect
complex SFCs or to give an overview of the relative size of SFCs.
I9 - SFC branches count
This number sums the number of branches in each AND/OR divergence found in a given SFC.
Comment : This rule calculates the number of branches available in a given SFC. This count gives information
about SFC complexity. This number is equivalent to the v(G) applied to imperative coding languages.
I10 - Copy/Paste detection ratio
This number detects the percentage of code which is redundant.
Comment : Reusing the code by copying code is not a good practice. Maintenance and evolution are more
expensive to perform because modications and corrections should be applied at each copy/paste instance. More-
over, the manual copy/paste is error prone : after doing the copy/paste, code should be modied. When code is not
modied correctly, it introduces subtle bugs hard to discover.
3.6 Options
3.6.1 Unity Project Options
O.U.1 - SFC : Multiple Token should not be Allowed
In the language extensions tab of project settings, the check-box Allow multiple token shall be deactivated.
Comment : The only purpose of the multiple token mode is to ensure backward compatibility with previous
versions of Schneider PLCs. It should not be used in new projects because it can make the code indeterministic.
SFC code with Multi Token is not compliant with IEC 61131-3.
Example: In the following SFC code, if the condition A is always true, after several PLC cycles, all steps
are simultaneously active.
14/19 January 20th 2012 - Version 1.6.7
PLC programs development guidelines
Figure 3.2: indeterministic SFC in multi-token mode
O.U.2 - SFC : Keep previous steps in active state should not be Allowed
In the language extensions tab of project settings, the check-box SetSteps: keep previous step(s) in active state
shall be deactivated.
Comment : This option is only available if the Allow multiple token check-box is activated - see O.U.1.
O.U.3 - SFC : Parallel branches: allow jump in/out should not be Allowed
In the language extensions tab of project settings, the check-box Parallel branches: allow jump in/out shall be
deactivated.
Comment : This option is only available if the Allow multiple token check-box is activated - see O.U.1.
O.U.4 - SFC : Only one evolutions by divergence of sequence selection
In the language extensions tab of project settings, the check-box Allow multiple evolutions by divergence of se-
quence selection shall be deactivated.
Comment : This option is only available if the Allow multiple token check-box is activated - see O.U.1.
O.U.5 - ST : Jump and label should not be Allowed
In the language extensions tab of project settings, the check-box Allow Jump and label shall be deactivated.
Comment : In general, usage of jumps reduces the readability of the code and therefore its maintainability.
O.U.6 - Identiers: leading digits in names should not be Allowed
In the language extensions tab of project settings, the check-box Allow leading digits shall be deactivated.
January 20th 2012 - Version 1.6.7 15/19
PLC programs development guidelines
Comment : In general, usage of leading digits in names reduces the readability and portability of the program.
O.U.7 - Identiers: the standard (IEC) character set shall be used in names
In the language extensions tab of project settings, the check-box standard shall be deactivated.
Comment : In general, usage of the non standard (IEC) character set in names , reduces the readability and
portability of the program.
O.U.8 - Graphical languages (FBD/LD): Usage of ST expressions should not be Allowed
In the language extensions tab of project settings, the check-box Usage of ST expressions shall be deactivated.
Comment : In general, usage of ST expressions in FBD reduces the readability of the program.
O.U.9 - Upload information: Upload information with comments and animation tables
In the Build tab of project settings (project generation settings) the following check-boxes shall be activated:
1. Include in the Upload information,
2. Comments (Variables and types) in the Upload information,
3. Animation tables in the Upload information
Comment : If the PLC memory allows, the storage of all upload information ensures a smooth restoration of the
source of the project from the PLC, thus improving the long term maintainability (lost backup issues).
O.U.10 - Ladder Diagram : Right-justify coils
In the Editors tab of project settings, the check-box Right-justify coils for Ladder Diagram (LD) shall be acti-
vated.
Comment : Right-justify coils allow a better readability of the program.
16/19 January 20th 2012 - Version 1.6.7
Chapter 4
Annexes
4.1 Summary of Rules
This annexe summarizes all the rules and useful information contained in this document.
Naming rules
N.1 - Non-specic - All elements of the program must be named
N.2 - Non-specic - Elements name length should be in a given range
N.3 - Non-specic - Topological physical address should not be used as part of a mnemonic
N.4 - Non-specic - Testing mnemonics should not be part of the nal program
N.5 - Non-specic - Special or graphical characters are prohibited in mnemonics
N.6 - Non-specic - The programming language keywords should not be used as mnemonics
Commenting rules
C.1 - Non-specic - All program elements should have a comment
C.2 - Non-specic - Comments should be longer than a given number of characters
C.3 - Non-specic - Each network should have a comment
C.4 - Non-specic - Comments should not only contain the comment start marker
Writing rules
E.1 - Non-specic - All variables should be written before being read
E.2.a, E.2.b - Non-specic - Inputs of the user functional blocks should be read and not written.
E.2.c, E.2.d - Non-specic - Inputs/Outputs of the user functional blocks should be read and written.
E.2.e - Non-specic - Outputs of the user functional blocks should be written before being read.
E.U.1 - SE Unity - The functions of the Unity obsolete libraries should not be used
17/19
PLC programs development guidelines
Structure rules
S.1 - Non-specic - Backward jumps are forbidden
S.2 - Non-specic - A variable should be elaborated only in one routine
S.3 - Non-specic - A variable should be written from one task only
S.4 - Non-specic - A physical output should be written only once per PLC cycle
S.5 - SE Unity - Variable should not be localized
S.6 - Non-specic - DFB/FBs instances should be called once
S.7 - Non-specic - Declared variables should be used
S.8 - Non-specic - Variables location doesnt overlap
S.9 - Non-specic - Complexity measure
S.10 - Non-specic - SCADA Limitations
Informations Utilities
I.1 - Non-specic - Comments rate
I.2 - Non-specic - Code in the comments
I.3 - Non-specic - Dead code
I.4 - Non-specic - List of locked elements
I.5 - Cyclomatic number v(G)
I.6 - Essential Complexity ev(G)
I.7 - Source Line of Code count
I.8 - SFC steps count
I.9 - SFC branches count
I.10 - Copy/Paste detection ratio
Options
O.U.1 - SE Unity - SFC : Multiple Token should not be Allowed ===
O.U.2 - SE Unity - SFC : Keep previous steps in active state should not be Allowed ===
O.U.3 - SE Unity - SFC : Parallel branches: allow jump in/out should not be Allowed ===
O.U.4 - SE Unity - SFC : Only one evolutions by divergence of sequence selection ===
O.U.5 - SE Unity - ST : Jump and label should not be Allowed ===
O.U.6 - SE Unity - Identiers: leading digits in names should not be Allowed ===
O.U.7 - SE Unity - Identiers:Using the standard (IEC) character set in names ===
O.U.8 - SE Unity - Graphical languages (FBD/LD): Usage of ST expressions should not be Allowed ===
O.U.9 - SE Unity - Upload information: Upload information with comments and animation tables ===
O.U.10 - SE Unity - Ladder Diagram : Right-justify coils ===
18/19 January 20th 2012 - Version 1.6.7
PLC programs development guidelines
4.2 Document history
Date Changes
2010
Jul 12th
Initial version
2010
Dec
21th
Add Options chapter
2011
Nov
9th
Add description for rules S5, S6, S7, S8, S9, S10, I5, I6, I7, I8, I9, I10
2011
Nov
21th
Add version number. Texts Corrections. Extend EU1 rule to all functions of the obsolete libraries
2012
Jan
20th
Proofreading and corrections (grammar, spelling) by Pauline
January 20th 2012 - Version 1.6.7 19/19