Should You Comment Every Detail?

James has touched on what I have always considered the key point of logic and its comments....who is going to be reading it at 0300h when the JIT line is down? If adding comments, even for the most obvious of logic, keeps my phone quiet all night, I'll gladly do it. And I'll make sure those accessing the logic know it's documented for them.
 
You can't over comment. Too many comments is like too much bacon or too much beer, not possible.

I disagree, too much commenting largely gets unread. Many people will just scroll past it because they believe they can decipher "the code".

Many of today's platforms allow for user-defined data types or structures, and the ability to create Add-On Instructions (is this unique to A-B/Rockwell ?), means that the documentation provided at the lowest level should inherently document what the code is attempting to achieve.

And let us not forget that mostly "documentation" may not be available, because in most systems this is not stored in the PLC. In those cases, you just have to work through the code, making up your own documentation as you go, which inevitably yields the documentation you needed, rather than someone else's interpretation of what they thought you needed !
 
I always try to put a date on my comments. I think it helps.


I do that too - together with a unique "marker" text I can later search for.

I have done a lot of modifications to systems created by "others", so anything I add or modify gets "tagged" in the documentation (usually rung comments, because I'm not changing data structure or context).


That unique "tag" text string can always be searched for in the rung comments later if anyone is interested.
 
Too much and too specific commenting becomes noise and very likely misleading when changes are made. You certainly can comment too much.
 
Too much and too specific commenting becomes noise
True if the programmer is blindly following a rule that every rung has to be commented and as a result ends up with comments like "This rung turns on the frammistat when the jaegernaut input is on". But, as others have noted, the comments should be an explanation of what the programmer was thinking at the time he/she wrote the program.

very likely misleading when changes are made
The original programmer has no control about what his/her successors or the end users do with the program. It is up to the people who make modifications to the logic to include the necessary modifications to the comments. A good job commenting in the first place improves the odds that the person making modifications later will know where in the logic to make the changes without incurring unanticipated consequences.

A good job of commenting also reduces the likelihood that someone will make an unnecessary "correction" to the logic when trying to sort out a problem. I've said many times that people will frequently assign blame to that which they understand the least. It's bad enough when people who don't know what the PLC is doing assume that any problems with the machine are due to the PLC program. It's equally bad when someone who knows what the PLC is capable of assumes the problem lies in that section of logic that he/she doesn't understand because the comments aren't clear about what it does.
 
as others have noted, the comments should be an explanation of what the programmer was thinking at the time he/she wrote the program.


Which would hopefully prevent situations where a maintenance tech or later programmer cries out loud: "what was he thinking??!! :mad:"




;)
 
Well formatted P&IDs incorporated into a formal tag name structure...E.g. AIN_1234_PV become self explanatory pretty quickly. Also, call me what you will but I structure my programs such that all timers are in a routine called "timers"...same thing goes with counters and such. Personally, it drives me nuts seeing timers sprinkled all over a program. I put them in P&ID numeric order as well. Makes it easier to find the things in a predictable way. Most important, to me at least, is that the variable names incorporate P&ID numbers in them. Search on that integer and you get specific results. Use names like 'recirc_water_pump' and things like that and the program code becomes a mess really fast.
 
Well formatted P&IDs incorporated into a formal tag name structure...E.g. AIN_1234_PV become self explanatory pretty quickly. Also, call me what you will but I structure my programs such that all timers are in a routine called "timers"...same thing goes with counters and such. Personally, it drives me nuts seeing timers sprinkled all over a program. I put them in P&ID numeric order as well. Makes it easier to find the things in a predictable way. Most important, to me at least, is that the variable names incorporate P&ID numbers in them. Search on that integer and you get specific results. Use names like 'recirc_water_pump' and things like that and the program code becomes a mess really fast.

Until the P&ID is lost and then it makes no sense at all, so why not both?
 
In the early days when symbols only had something like 8-16 chars a system we used was for example TK1V01SO or TK1V01OP or TK1V01CL so this meant Tank1, Valve 1, Solenoid 1, Open limit, Closed limit, not perfect due to limited chars but it tied in with the Graphics (HMI), P&ID, electrical drawings for a process plant rung comments gave it a bit more information regarding the operation. Nowadays with symbols of 32 chars & almost limited rung comments it is easier but it makes sense to still use some kind of structure to the symbols that is a reflection of the drawings/graphics. I also think that reasonable comments will do but any information as to what the logic is doing can be helpful, it is a balance of giving enough detail to understand what the logic is doing but not too much that the costs of the time it takes to comment fully are not viable.
 

Similar Topics

Hi, I am working on automating an industrial fabric shrinkage tester to replace its outdated electronics with a PLC. To get the tank's water level...
Replies
14
Views
502
In a control System, I need to move 3 motors attached to roller in stages with speed of 1 to 2 RPM and the torque of motor should be 8-10 Nm...
Replies
0
Views
816
Hi, I want to build a production line project using a PLC. This is the project page...
Replies
14
Views
2,059
See picture. I want to add a rung (magenta) into the existing code. Can't figure out how to do this. I select a -||- , right? When I drag/drop...
Replies
21
Views
1,700
Sorry for the basic question: On my HMI, I've created a button labelled SAVE to save the current values (distances in mm). It's not linked to any...
Replies
22
Views
2,133
Back
Top Bottom