A Control Design reader writes: When programming, what is the best approach for documentation of the code?
Answers
Follow the rabbit trail
You could say that proper program documentation is in the eye of the beholder. It is a rather subjective topic, but the overall goal is to communicate the intent of the machine level instructions used in programming environments. Well-written code can be self-documenting in some respects, but this usually requires familiarity with the programming language. The language of programming is built for efficiency, not necessarily easy readability, so it often becomes necessary to add documentation to provide more context or to communicate intent of code design. Revision control provides an historical documentation that is valuable to keep track of enhancements along the life of the code without polluting the code with too much text.
Program documentation can happen within the code itself using documentation features of the integrated development environment (IDE). For ladder logic, that might mean commenting rungs of code or headers for programs or tasks. For text-based code, it is simply ‘commented out’ lines within the code itself. The comments leave a rabbit trail of important functions within the actual code. It is useful to explain certain functions and help someone who is following the code to know how the code works. It is particularly useful to explain calculations that might not be apparent from the data points that are collected in the program. Naming conventions of data points and variables help to make the code easier to write and more efficient to read, as long as the naming convention is documented for the next reader.
Revision control is important to understand the history of the code, documenting changes along the way. Major updates and revisions can be tracked to assist in troubleshooting if some problem is discovered later. A record of new feature additions can be recorded to see when new functions became available. Revision control provides a base structure for branching into different sets of code that have different functions. GitHub is a popular website for managing version control using Git, an open-source software used in Linux since 2005. It is one of the most popular repositories of source code in the world and widely used in the software development community. As industrial controllers move more toward using the tools of modern, non-industrial software development, revision control tools like GitHub are being integrated directly into industrial programming IDEs.
Allen Tubbs / product manager/ Bosch Rexroth / www.boschrexroth.com/en/us/
How input affects output
Proper documentation of code depends on the documentation’s eventual use. If the purpose of the documentation is to help with troubleshooting, then I would first recommend investigating the type of code being used. Ladder code is great for troubleshooting because it easily helps engineers to see how inputs are affecting outputs. Sequential function charts are another great option for troubleshooting. They can provide intuitive visual cues to where the logic is at and what the code is waiting for to continue.
Whatever the purpose of the documentation, it is always imperative to be mindful of the audience. Documentation should be written in a way that clearly translates the code in plain language. Simplicity is the name of the game—the goal should be writing the documentation as if you were explaining to an elementary school student what the block of code does.
Kris Dornan / marketing manager, Logix controllers / Rockwell Automation / www.rockwellautomation.com
Break the code
This changes greatly with the type of code that you are doing. In general, if you can give very descriptive tag (variable) names and give your function instances descriptive names you have made very readable code. To get more specific, for PLC code I would place a rung comment on each significant rung. By this, I mean when you move from controlling one part of a system to a different part, document that change with rung comments. For more of a text or SFC type program, you have a lot more flexibility in your documentation. Here I would suggest that you break your code into chunks that are well described so that you can debug starting at where the problem is evident and work through the chunks that contain the source data. Really, as far as the best practices for program documentation go, as long as it is there and the variables are understandable any further tips inside the code is icing on the cake for the next programmer to enjoy.
Mark Russell / tech application support manager / Allied Electronics & Automation / www.alliedelec.com
Multiple programs and languages
First things first. Ultimately, PLC code is used to control a machine or system. Therefore, the goal of documenting any PLC code is really about documenting the machine or system, and documentation begins during the system design phase. System documentation should describe the overall architecture, configuration, I/O wiring diagrams and what the system does. Clearly defining the system also gives you a clear view on structuring the PLC program.
PLCs are very flexible and allow you to structure a PLC project as multiple programs, each of which can also be broken down into smaller units. For example, you can have an initialization program to load parameters on power-on, and a separate program for executing the main routine of the system. Clearly define the names of these programs and what each program does. Also define your variables. A table of variable definitions provides important context for anyone looking at code.
There are also some standards that exist to help provide standard structure and terminology. For example, Mitsubishi Electric is able to provide PackML sample projects with defined machine operation modes and state transitions.
During the design phase, you also have a choice of programming languages between ladder diagram, function block diagram, structured text and sequential function chart. And it doesn’t have to be only just one. A single PLC project can be comprised of multiple programs written in different languages that best suit the particular purpose. When programming in ladder diagram, add rung comments. Function block diagram, structured text, and sequential function chart languages allow for comments to be written anywhere. Take advantage of this to clearly describe what the code is doing.
With PLCs and increased memory capacity, the comments also stay with the code when downloaded to the PLC. This is a great benefit because even if the original project file is lost, you can retrieve the code and comments by uploading from the PLC.
In the end, the purpose of documenting PLC code is to make sure that the code can be maintained, so that programmers, technicians and customers can troubleshoot, modify or add to the program as desired. The easier it is to understand what the program is doing, the easier it is to support.
Lee Cheung, Sr. / product marketing engineer / Mitubishi Electric / us.mitsubishielectric.com/en/
