There are a couple of different ways of thinking when it comes to in-program documentation, particularly the use of comments.
One main methodology I see is to use documentation liberally (since it’s free), placing comments on as many rungs as desired.
The other methodology is that less is more, with more emphasis placed on variable tags and organization.
There is no doubt that there are times when a well-written comment can be very beneficial, particularly on the older programming platforms where the variables may have naming limitations.
In some cases the work could be for nothing when the variable tags and comments do not get saved in the processor.
My opinion is that a well-organized program with useful and verbose variable tags (aliases) can eliminate the need for comments altogether.
Using Verbose Comments To Document Hard To Follow Code
First, I’ll explain the issue that I have with comments. Fundamentally, comments are most often used to explain logic that is hard to follow.
This can lead to logic that could have been factored better to be easier to understand.
Sometimes it is best to write logic that is longer overall if it has a better flow and is easier to read.
Imaging you are reading an old undocumented program that only contains variable addresses.
If there is a good flow to the logic, you can often understand it. If there isn’t it can be very difficult, even with comments.
Sometimes because every rung is commented, there can be comments on basic logic that is easy to understand and doesn’t need any. The thought is to be consistent, which is generally a great thing, but it can make the program appear cumbersome.
Imagine you do have a program as described in the above paragraph. It is generally well-written and every rung has a comment regardless of what is going on.
When you go to commission the program, you will inevitably find some things that you have to correct.
Since there are so many comments, you not only have to get down and fix the logic, but now it is expected of you to also maintain all of these comments. This could mean adding new comments as well.
You will have to check the rest of the program logic and comments to make sure they still remain valid after the changes. This adds to the overhead of maintaining the program.
Using Descriptive Tag Names With Logic That’s Easy To Understand
Deciding to forego comments is a methodology that you have to adopt early in the program design, as choosing descriptive yet concise variable tags is a key part of the process.
For example, in a standard start/stop program for a motor starter, you may have labeled the inputs as “START_PB”, “STOP_PB” and “MOTOR_OL”. The output could be labeled as “MOTOR_STARTER”.
The comment (may not exist due to the simplicity of the logic) could have read “START/STOP MOTOR STARTER LATCH”.
Sidebar: Studies have shown that people read mixed case (capitalizing only the first letters) words with better understanding, so consider replacing a text such as “MOTOR_STARTER” with “Motor_Starter”. The studies were primarily regarding the readability of street signs, but it is something to consider.
With most modern programming environments, the variable tags can be quite long, so a more descriptive and comment-like tag can be used such as “Start_Motor_Pushbutton”.
Choosing proper variable tags is the first part of making this work, but the logic must also be written in the most readable way possible.
This may not always be the most efficient way, and if there is a lot of nested logic in a procedure it may be better to segment it into several rungs for readability.
The Figures 1 and 2 below show how this may be done with a single rung and comments compared to using four rungs with verbose variable tags and no comments.
In the above example, each rung in figure 2 is clearer and so basic that comments are not needed.
Programming in this way can also make future modifications easier as there won’t be a need to maintain comments, and the logic is segmented so it can be easier to add new inputs to the proper areas.
It’s also important to keep in mind that there is no practical limit on the number of internal variables you can use, so adding additional internal tags or coils is not going to affect the program in any noticeable way.
You don’t have to take the premise of eliminating comments literally. The point of this is to promote a different way of looking at program organization.
You will certainly find that by using better variable names and logic flow will make your programs more readable and understandable to a larger group.
And even more efficiencies can be achieved by creating and using your own data types and instructions, which I cover that in tomorrow’s article.
Written by Carlo Zaskorski
Controls Engineer, Product Manager, and Freelance Blogger
Edited by Shawn Tierney
Have a question? Join our community of pros to take part in the discussion! You'll also find all of our automation courses at TheAutomationSchool.com.
Sponsor and Advertise: Get your product or service in front of our 75K followers while also supporting independent automation journalism by sponsoring or advertising with us! Learn more in our Media Guide here, or contact us using this form.
- The Realities of Project Management: Know When to Hold ‘Em, Know When to Fold ‘Em - December 23, 2019
- The Realities of Project Management: The Project Czar - December 5, 2019
- The Realities of Project Management: The Second Effort - November 21, 2019
