Programming PLCs: Keep the documentation clear and simple

Poor programmable logic controller documentation and housekeeping can lead to unnecessary troubleshooting and downtime. Keep it simple in order to avoid the possible risks and confusion.

05/20/2014


Different rules and programming methods are needed based on the hardware and software being used. Programming in a Siemens programmable logic controller (PLC) is not identical to programming in an Allen-Bradley PLC. There are general good practices that should be followed in any programming. The obvious is to have the program function and control as desired. Maintaining good documentation and housekeeping are good general practices in programming. Code should be easily read and understood by programming colleagues and customers. Poor documentation and housekeeping can add unnecessary time to troubleshooting, downtime, and programming. Programming structure and how complicated it may or may not be is another variable that will affect how easily the code is deciphered. I suggest following the KISS principle: “Keep it simple, stupid.” Avoid unnecessary complexity and keep it simple and straightforward.

Easy living through documentation

Good documentation will make your programming life easier. Adding rung comments and descriptions to tags greatly helps understand the code and the process that the code is controlling. Typically, if a programmer has an allotted schedule to program, documentation is not a problem. It might become a problem when time is running out and code needs to be cranked out, with the mind-set that the programmer will add the documentation at a later time—but that later time may or may not come.

Keeping up with documentation while commissioning code can prove difficult; at the time of commissioning, the priority is ensuring the code is functional and meets customer processing needs. Having multiple programmers on the same PLC program might also cause some distress with documentation. Communication and coordination between the programmers will help minimize the loss of documentation.

Document unto others, as...

Documentation is critical in that it helps the customer/programmer understand more easily what is going on or the code’s intent. I suggest to program with the mind-set that you, the programmer, will need to maintain it. Typically, we program and walk away from a site and might not return to the site for a long period of time. It will be nice if you return to the site to add code for a new process or enhancing their process and you can easily understand what you wrote several years before with little to no effort. The same goes with other programmers within your company or other subcontractors that the customer might hire. Sure, we can easily determine that we can write the code in the most complex way and have little to no documentation to make the other guy depend on you to make any programming updates or changes. While this might sound good for job security, it is not good practice. Customers will not appreciate relying on the one guy. Customers typically want off-the-shelf parts to ease maintenance and downtime; the same concept can be applied to programming. Customers typically steer away from custom software and would rather move to something that has an open source code and good software support—whatever makes sense to minimize possible future downtime and future upgrades, enhancements, and additions.

Code: Keep it clean

With documentation, another good practice is housekeeping: keeping the code clean and removing tags and code that simply go nowhere and are not needed. As programmers we typically take our best practices to new projects, especially if the new project has no predetermined code structure standard. After all, why reinvent the wheel? But while doing so, we need to remove whatever code we carried over from our copy-and-paste that is not needed—cut the fat. As a programmer, it’s not easy going into a program that has little or no documentation; and it doesn’t help that after reverse engineering the code, you discover that a percentage of the code is bogus and unneeded. After a few choice words, the first question you ask yourself is, who wrote this? Don’t be that programmer.

 

Good documentation and housekeeping are good programming practices. I’m sure we all have run into a program that had little to no documentation; many hours were required to reverse engineer what the program is doing. Even if the program documentation is written in a language foreign to your own, at least there is documentation. Google Translate to the rescue.

This post was written by Miguel Guiterrez. Miguel is a Senior Control System Specialist at MAVERICK Technologies, a leading automation solutions provider offering industrial automation, strategic manufacturing, and enterprise integration services for the process industries. MAVERICK delivers expertise and consulting in a wide variety of areas including industrial automation controls, distributed control systems, manufacturing execution systems, operational strategy, business process optimization and more. 



Engineers' Choice Awards
The Engineers' Choice Awards highlight some of the best new control, instrumentation and automation products as chosen by Control Engineering subscribers. Vote now (if qualified)!
System Integrator Giants
The System Integrator Giants program lists the top 100 system integrators among companies listed in CFE Media's Global System Integrator Database.
System Integrator of the Year
Each year, a panel of Control Engineering and Plant Engineering editors and industry expert judges select the System Integrator of the Year Award winners in three categories.
How to Maximize Factory Automation Efficiency with Low Cost Machine Vision
This eGuide illustrates solutions, applications and benefits of machine vision systems.
Wireless Reliability in Harsh Environments
Learn how to increase device reliability in harsh environments and decrease unplanned system downtime.
Human Factors and the Impact on Plant Safety
This eGuide contains a series of articles and videos that considers theoretical and practical; immediate needs and a look into the future.
May 2018
Salary and Career Survey, IT and OT convergence, robotic standards and safety, secure circuit protection
April 2018
Cybersecurity best practices, artificial intelligence, robotic additive manufacturing, embedded systems, IIoT integration, energy efficiency
March 2018
Digitalization integration, process sensors, edge computing, fog computing, condition monitoring, and motors
Edge Computing
This article collection contains several articles on how today's technologies heap benefits onto an edge-computing architecture such as faster computing, better networking, more memory, smarter analytics, cloud-based intelligence, and lower costs.
IIoT: Machines, Equipment, & Asset Management
Articles in this digital report highlight technologies that enable Industrial Internet of Things, IIoT-related products and strategies.
PLCs
Programmable logic controllers (PLCs) represent the logic (decision) part of the control loop of sense, decide, and actuate. Featured articles in this digital report compare PLCs and programmable automation controllers (PACs), industrial PCs, and robotic controllers.
SIDB

Find and connect with the most suitable service provider for your unique application. Start searching the Global System Integrator Database Now!

April 2018
ROVs, rigs, and the real time; wellsite valve manifolds; AI on a chip; analytics use for pipelines
February 2018
Focus on power systems, process safety, electrical and power systems, edge computing in the oil & gas industry
December 2017
Product of the Year winners, Pattern recognition, Engineering analytics, Revitalize older pump installations
John O. Ayuk, PE, CFSE, PMP, CAP
Automation Engineer; Wood Group
Doug Baker
System Integrator; Cross Integrated Systems Group
Jose S. Vasquez, Jr.
Jose S. Vasquez, Jr.
Fire & Life Safety Engineer; Technip USA Inc.
Data Centers: Impacts of Climate and Cooling Technology
This course focuses on climate analysis, appropriateness of cooling system selection, and combining cooling systems.
Safety First: Arc Flash 101
This course will help identify and reveal electrical hazards and identify the solutions to implementing and maintaining a safe work environment.
Critical Power: Hospital Electrical Systems
This course explains how maintaining power and communication systems through emergency power-generation systems is critical.
Engineers' Choice Awards
The Engineers' Choice Awards highlight some of the best new control, instrumentation and automation products as chosen by Control Engineering subscribers. Vote now (if qualified)!
System Integrator Giants
The System Integrator Giants program lists the top 100 system integrators among companies listed in CFE Media's Global System Integrator Database.
System Integrator of the Year
Each year, a panel of Control Engineering and Plant Engineering editors and industry expert judges select the System Integrator of the Year Award winners in three categories.
How to Maximize Factory Automation Efficiency with Low Cost Machine Vision
This eGuide illustrates solutions, applications and benefits of machine vision systems.
Wireless Reliability in Harsh Environments
Learn how to increase device reliability in harsh environments and decrease unplanned system downtime.
Human Factors and the Impact on Plant Safety
This eGuide contains a series of articles and videos that considers theoretical and practical; immediate needs and a look into the future.
May 2018
Salary and Career Survey, IT and OT convergence, robotic standards and safety, secure circuit protection
April 2018
Cybersecurity best practices, artificial intelligence, robotic additive manufacturing, embedded systems, IIoT integration, energy efficiency
March 2018
Digitalization integration, process sensors, edge computing, fog computing, condition monitoring, and motors
Edge Computing
This article collection contains several articles on how today's technologies heap benefits onto an edge-computing architecture such as faster computing, better networking, more memory, smarter analytics, cloud-based intelligence, and lower costs.
IIoT: Machines, Equipment, & Asset Management
Articles in this digital report highlight technologies that enable Industrial Internet of Things, IIoT-related products and strategies.
PLCs
Programmable logic controllers (PLCs) represent the logic (decision) part of the control loop of sense, decide, and actuate. Featured articles in this digital report compare PLCs and programmable automation controllers (PACs), industrial PCs, and robotic controllers.
SIDB

Find and connect with the most suitable service provider for your unique application. Start searching the Global System Integrator Database Now!

April 2018
ROVs, rigs, and the real time; wellsite valve manifolds; AI on a chip; analytics use for pipelines
February 2018
Focus on power systems, process safety, electrical and power systems, edge computing in the oil & gas industry
December 2017
Product of the Year winners, Pattern recognition, Engineering analytics, Revitalize older pump installations
John O. Ayuk, PE, CFSE, PMP, CAP
Automation Engineer; Wood Group
Doug Baker
System Integrator; Cross Integrated Systems Group
Jose S. Vasquez, Jr.
Jose S. Vasquez, Jr.
Fire & Life Safety Engineer; Technip USA Inc.
Data Centers: Impacts of Climate and Cooling Technology
This course focuses on climate analysis, appropriateness of cooling system selection, and combining cooling systems.
Safety First: Arc Flash 101
This course will help identify and reveal electrical hazards and identify the solutions to implementing and maintaining a safe work environment.
Critical Power: Hospital Electrical Systems
This course explains how maintaining power and communication systems through emergency power-generation systems is critical.
Engineers' Choice Awards
The Engineers' Choice Awards highlight some of the best new control, instrumentation and automation products as chosen by Control Engineering subscribers. Vote now (if qualified)!
System Integrator Giants
The System Integrator Giants program lists the top 100 system integrators among companies listed in CFE Media's Global System Integrator Database.
System Integrator of the Year
Each year, a panel of Control Engineering and Plant Engineering editors and industry expert judges select the System Integrator of the Year Award winners in three categories.
How to Maximize Factory Automation Efficiency with Low Cost Machine Vision
This eGuide illustrates solutions, applications and benefits of machine vision systems.
Wireless Reliability in Harsh Environments
Learn how to increase device reliability in harsh environments and decrease unplanned system downtime.
Human Factors and the Impact on Plant Safety
This eGuide contains a series of articles and videos that considers theoretical and practical; immediate needs and a look into the future.
May 2018
Salary and Career Survey, IT and OT convergence, robotic standards and safety, secure circuit protection
April 2018
Cybersecurity best practices, artificial intelligence, robotic additive manufacturing, embedded systems, IIoT integration, energy efficiency
March 2018
Digitalization integration, process sensors, edge computing, fog computing, condition monitoring, and motors
Edge Computing
This article collection contains several articles on how today's technologies heap benefits onto an edge-computing architecture such as faster computing, better networking, more memory, smarter analytics, cloud-based intelligence, and lower costs.
IIoT: Machines, Equipment, & Asset Management
Articles in this digital report highlight technologies that enable Industrial Internet of Things, IIoT-related products and strategies.
PLCs
Programmable logic controllers (PLCs) represent the logic (decision) part of the control loop of sense, decide, and actuate. Featured articles in this digital report compare PLCs and programmable automation controllers (PACs), industrial PCs, and robotic controllers.
SIDB

Find and connect with the most suitable service provider for your unique application. Start searching the Global System Integrator Database Now!

April 2018
ROVs, rigs, and the real time; wellsite valve manifolds; AI on a chip; analytics use for pipelines
February 2018
Focus on power systems, process safety, electrical and power systems, edge computing in the oil & gas industry
December 2017
Product of the Year winners, Pattern recognition, Engineering analytics, Revitalize older pump installations
John O. Ayuk, PE, CFSE, PMP, CAP
Automation Engineer; Wood Group
Doug Baker
System Integrator; Cross Integrated Systems Group
Jose S. Vasquez, Jr.
Jose S. Vasquez, Jr.
Fire & Life Safety Engineer; Technip USA Inc.
Data Centers: Impacts of Climate and Cooling Technology
This course focuses on climate analysis, appropriateness of cooling system selection, and combining cooling systems.
Safety First: Arc Flash 101
This course will help identify and reveal electrical hazards and identify the solutions to implementing and maintaining a safe work environment.
Critical Power: Hospital Electrical Systems
This course explains how maintaining power and communication systems through emergency power-generation systems is critical.
click me