Software Etiquette

When writing software, it’s important to write code that is organized and contains descriptive comments. This helps the code be more readable when the programmer goes back to it to make changes or debug. However, not just the original programmer needs to be able to decipher the software. Sometimes other programmers need to examine or modify code that was written by someone else. That’s why it’s best practice to write code with good etiquette and other programmers in mind. Here are some tips for writing PLC software with proper etiquette.

Set Ladder Logic to Match Page Width

The image below shows a rung of ladder logic in a Siemens PLC using TIA Portal. Looking at the image, the entire network can’t be read because it is too long and continues off the right side of the viewing window. The user must scroll horizontally to view the rest of the instructions.

Figure 1: Long Network Out of View

Long networks such as the one above can be restructured to perform the same instructions but in a way that is easier to read. The same network from the image above is shown restructured in the image below.

Figure 2: Restructured Network

In the image above, all the instructions can be seen without having to scroll horizontally. When the PLC runs, both networks do the exact same thing, but the second image is easier to read and monitor.

Establish and Follow a Naming Convention

When setting up a new program, the programmer often has the freedom to create their own block names, variable names, network titles, and etc. Choosing a straightforward, effective naming convention makes a program much easier to navigate and understand. The image below shows a simple naming convention for block titles in Siemens TIA Portal.

Figure 3: Block Title Naming Convention

In this example, each block title starts with it’s block type, then a space, then a block description written as all one word with CamelCase capitalization. It’s a simple thing to do, but it keeps the project clean and organized for the next programmer or maintenance technician that might need to look through the code only to make a minor change. Another reason to maintain a consistent naming convention is to be able to use Find and Replace more efficiently. If there is a known naming convention for inputs and outputs, and something needs to be reprogrammed, Find and Replace can be used to make big changes very quickly.

Leave Meaningful Comments

Most people would say that writing software with meaningful comments is common sense, but when writing large programs with a deadline fast approaching, it’s easy for commenting to get forgotten. However, comments are especially important for exception cases where something may need to be added to the program later. The example in the image below shows where a comment may be especially important.

Figure 4: Network Comment Example

The example above might be confusing to come across without a meaningful network comment or memory addresses. However, with the descriptions pictured, future programmers should know exactly what to do when they encounter this network. If they need more assistance, they know who originally wrote the logic to contact for more information.

These and many other programming practices help to keep software code accessible for the original programmer and anyone who may need to read the code later. If everyone follows good software etiquette, reading other programmers software will be easier and more efficient for all of us.