Why You Should Insist on Documented Code for Every New Process Control Project

The following tip is from the ISA book by Greg McMillan and Hunter Vegas titled 101 Tips for a Successful Automation Career, inspired by the ISA Mentor Program. This is Tip #26.

101 Tips for a Successful Automation CareerOne of the toughest jobs is to work on a program that involves thousands of lines of complex, undocumented code.

Concept: Documenting software code does not take a great deal of effort, but most programmers are loath to do it. Despite how they may feel, insist that all code include at least a minimum of documentation.

Details: Everybody understands the code that THEY wrote, but eventually some poor soul has to tweak or troubleshoot that code years after it was written, and he or she may be in for a battle if the original software was never documented. Occasionally, Karma prevails, and the original programmer has to go back and rework his own code 10 years later. Even though he wrote it, the programmer will often find it impossible to remember his thought processes 10 years after the fact.

It does not take that much effort to create meaningful variable names and descriptions and drop in a comment or two that explains what is happening in the software. However, it can take days (or weeks) to try to understand a complex piece of code and figure how to modify it as necessary. Programmers, take the extra few minutes and explain what is going on. This is especially important if the code is involved or uses subtle “tricks” to accomplish a particular task.

When creating variable names and descriptions, try to reference the field tag number and its function. This makes the tag much easier to recognize. In addition, try to be as consistent as possible when assigning these descriptions. Working on a system that was programmed by multiple people can be extremely difficult if every section reads and is documented differently.

Watch-Outs: Many third-party vendor packages incorporate a PLC with no documentation whatsoever. Insist on documented code in your original bid spec.

Exceptions: None.

Insight: Back in the dark ages, PLC memory was expensive, and programs were written to conserve that memory as much as possible. Programmers used software pointers, tables, and rack addressing to accomplish certain tasks and most failed to document anything. In many cases, the slightest modification to the program could shift the registers, and suddenly everything would be pointing to the wrong place. It was great job security for the guy who wrote it, but they were rarely asked to write anything else!

Rule of Thumb: Take a moment and sprinkle comments through the software during programming. Ten years from now you (or someone else) will be very glad that you did.

Hunter Vegas

About the Author
Hunter Vegas, P.E., holds a B.S.E.E. degree from Tulane University and an M.B.A. from Wake Forest University. His job titles have included instrument engineer, production engineer, instrumentation group leader, principal automation engineer, and unit production manager. In 2001, he joined Avid Solutions, Inc., as an engineering manager and lead project engineer, where he works today. Vegas has executed nearly 2,000 instrumentation and control projects over his career, with budgets ranging from a few thousand to millions of dollars. He is proficient in field instrumentation sizing and selection, safety interlock design, electrical design, advanced control strategy, and numerous control system hardware and software platforms.
Print Friendly, PDF & Email

, , , , , ,

Pin It on Pinterest

Shares
Share This

Share This

Share this ISA post with your friends!