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, and was written by Hunter.
One 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.
About the Author
Gregory K. McMillan, CAP, is a retired Senior Fellow from Solutia/Monsanto where he worked in engineering technology on process control improvement. Greg was also an affiliate professor for Washington University in Saint Louis. Greg is an ISA Fellow and received the ISA Kermit Fischer Environmental Award for pH control in 1991, the Control magazine Engineer of the Year award for the process industry in 1994, was inducted into the Control magazine Process Automation Hall of Fame in 2001, was honored by InTech magazine in 2003 as one of the most influential innovators in automation, and received the ISA Life Achievement Award in 2010. Greg is the author of numerous books on process control, including Advances in Reactor Measurement and Control and Essentials of Modern Measurements and Final Elements in the Process Industry. Greg has been the monthly "Control Talk" columnist for Control magazine since 2002. Presently, Greg is a part time modeling and control consultant in Technology for Process Simulation for Emerson Automation Solutions specializing in the use of the virtual plant for exploring new opportunities. He spends most of his time writing, teaching and leading the ISA Mentor Program he founded in 2011.
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. Hunter 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.