Should You Comment Every Detail?

Commenting is important, as is keeping to a standard in coding (a lot doesn't have to be said if it's consistent), deleting dead code and updating IO lists and address tags/symbols. Obviously a lot of this doesn't apply to brand new code, but after a couple of years, the comments end up being the least of it.

when downtime is important to be kept to a minimal, the good comments are very helpful.

If you make an AOI out of structured text. May not need to comment that. But it the running logic, you should for troubleshooting purpose, unless you are trying to secure your own work.



I know a company that used DirectLogic just for the purpose of being different than everyone else, and cheap to win bids. Never provided the comments in case he had any of his own.



I have had to comment programs far too many times. Makes one learn other peoples logic very well though.

I think I saw it said best with some ones signature on here.

"Comments should be like a skirt, long enough to cover the important parts but short enough to keep it interesting."

Comment is also for yourself, like 5 years later. You know, when you look at your own code and ask which idiot did it.

As other said, a excellent (not just good) programmer should have codes that are almost self-explanatory.

The one type of comment I see missing is the "why" comment. The "what" part should be clear enough (again, if you are a decent programmer), but the "why" part is what illuminates the overall structure of the program.

Saffa said:

My technique is to just call every variable Temp1, Temp2, TestBit7 etc. That communicates to the people following that this was a half assed project done in a few hours before commissioning date, which couldn't be moved even though civil, mech and elec were all weeks behind. That way they'll completely understand your shortcomings, even if they can't understand your code.

Use inappropriate programming techniques to show people you can bend any code to your will, because flexibility is weakness. Using a single state machine for controlling multiple interdependent processes is a great technique. Refuse to use DFBs / AOIs, because you didn't need them in 1995, so why do you need them now?

Always buy the cheapest, least functional controller. A Zelio Smart relay is perfect for running a continuous process plant. Use 95% of the memory so any future additions need to follow your spartan resource allocation techniques.

Click to expand...

I've got a couple of your machines where I work, and would just like to say ******* and the horse you road in on! :angr:

Seriously, the best definition of how many comments are appropriate I have heard was that they should be like skirts. Long enough to cover the essentials.

Bubba

Of equal importance, is why things are done relative for the machine/process operation.

IMHO, commenting a MOV Length LengthLast is not really required, but perhaps
‘Capture last length for datum of next run’ is meaningful..

Because I have a terrible memory, I usually comment to help myself work out what I've done and how I've done it. I don't comment on every rung, just sections. I.E. I comment "in this section i'm collecting the input x.x and using it to start a timer x. Once this expires it will trigger output x.x" and the like.

bob1371 said:

i've never had anyone complain that i over commented my logic.

Click to expand...

+1

Rung comments don't need to state the "what" so much as they should document the "why" and "how". If the rung comment is just an English translation of the rung, it is not very useful. I like to comment every address that is used, reserved for future use, or likely to be used in the code. I prefix all the addresses from the HMI/SCADA with "TO HMI ..." or "FROM HMI ..." and addresses to and from other comms devices similarly.

I don't comment every rung, just sections as said by others. I like to make use of RSLogix 500 page titles and Advanced diagnostics integrated into the program tree for handy navigation.

Keep it short and sweet - but most of all keep it relevant and informative...

You, as the programmer, should know when you've done something that others may not be able to grab the handles of, so document it accordingly.

Avoid using phrases like "I've been clever here ...." no-one will thank you for it, just document what it does and how it does it, especially if it is not clearly obvious.

Don't over-document, that can be as bad as under-documenting.

99% of people who will be maintaining the systems will (or should, if they are going online) have a good understanding of what each instruction does, and why it was used in the context.

Incorporate aspects of the process into your documentation whenever you can - at the end of the day the PLC will be doing a real job, and reference to the real-world would be helpful to others.

You can never "over-document" a project, but you can sure do the opposite.

willxfmr said:

I've got a couple of your machines where I work, and would just like to say ******* and the horse you road in on! :angr:

Click to expand...

Like our after sales support and any kind of warranty, ****'ing the horse will cost you extra.

Well, just to add on to the horse story, one of the OEM that supplied piece of equipment solved the commenting issue.

By locking down the logic so we have no access to it what so ever.

I do a few things in my comments. I start off my main routine with a table of contents that logically outlines my program and some unique identifier that I won't use anywhere else, like: Main:1.A or something. Then I can use search for Main:1.A and go right to that section of the code. I don't put too many descriptions in the ToC. It is mainly meant for quick navigation.

Then, at my section, such as Main:1.A, I will describe the purpose of the section and any important notes about this section. I put in a short theory of operation, and if there are any weird things I did in that section.

Then, I make note of each "sub-section" of logic. They are usually short:

**Start/Stop logic*

**Alarm bits for Start/Stop**

**Sequence flags for Start/Stop**
**Note about how my sequence flags are all strange because of some weird quirk in the HMI's firmware that required some non-standard BS that breaks my pattern**

Then, I use descriptive tags where possible to name the component, usually to match my IO and labels. That is where AD Productivity stuff is nice, too. They have a property field that allows you to put the wire tag on an IO point so you can search that way. Pretty cool feature.

I do not comment obvious logic.
I only comment on a more complicated section using multiple rungs.
I comment to help others understand what I did and for the purpose of not adding logic between the rungs that are functioning as a group to perform a function.
I comment to remind myself of what I did.

Over the last 30+ years, i have seen many types of programs, program styles, comments, and lack there of.
Everyone on the forum should agree that maintenance is it backbone of the plant and they are the ones who keep it running.
I try to do the following: Write the detailed sequence of events in the operations manual including i/o points, timers, counters. sometimes this gets lost (usually not once i show maintenance what is in the manual). i then comment a rung that briefly describes what will happen in the next 5 rungs as an additional safety to help maintenance.

All programs should be written in such a way that it is easy to follow the logic in order in a step by step manner. use comments to help describe what is happening. separate machine stations into their own subroutines to help simplify things. a 2400 rung program composed of 14 workstations written into 1 main ladder program is confusing and hard to troubleshoot, but that same program written is subroutine form helps pinpoint what station to look at and trouble shoot. it may only have 200 rungs, not 2400.

Everyone on the forum has their own programming style and method of documentation. i find that working with maintenance and learning what their capabilities are goes a long way. they will bend over backwards to try to solve the issue before calling you. BUT ! throwing a machine at them and not training maintenance will get you noticed by everyone in the plant ! maintenance can't fix the issue, no training, management hears of it, plant manager calls your boss, then you get the calls at all hours of the night. don't forget the possible downtime penalties in the contract. downtime costs can range from nothing to $1200 per minute where i used to work to $10,000 per minute for a tier 1 supplier running the just in time method (stupid if you ask me).
regards,
jams