Instruction and Rung Comments

[The Plc Kid]

Just wanted to get some feedback on instruction comments and rung comments.

I use a lot of rung comments and I try to make sure there is a description / comment on each instruction within reason.

What I wanted to know about is the format of the text. Do most like it to all be caps? All lower case? The first letter of each word caps?

Speaking primarily logix 5000 but also 5 and 500

Which method works best and why. I have a mix of all of them here. I know it is just personal preference but just wanted opinions of others on what they think works best in the field.

Thanks

 

[brucechase]

Rung comments I do in sentence structure. Cap the first word only. Instruction comments I do in all caps.


Didn't vote because not a choice and I mix the styles.

 

[rdrast]

Tagnames - CamelCapsLikeThis
Rung and instruction comments are typed out exactly as I would type out a message here.

 

[OkiePC]

I have seen some people apply strategies here, and I tend to like these:

All caps only for real I/O. Variaton: Only use symbol names for real I/O

All addresses used in HMI tags prefixed with "HMI " or "From HMI " or "To HMI" Variation: Prefix all HMI symbols with "PV_" or "HMI_"

Always describe input devices states in their true condition

Rung comments that restate the obvious are useless. Tell me about why you do something unusual in code. I can see that "when the operator presses button x the motor runs until the stop button turns it off" So simple plain logic is self explanatory, rung comments just get in the way.

Now, if the rung has some math or conditions or is rather complex, then a comment in called for, but not one that just restates in english what the rung does...I wanna know why, or what changes have been made or what real world reasons there are for interlocks, etc...

If it's the first rung of a subroutine, give me an overview of the purpose, and perhaps a list of in/out definitions. I like the very first rung of a program to include IP addresses or connectivity info, especially if there is a bridge module (like a NET-ENI) involved. If the first rung comment has the IP address of the ENI, this will me get online without having to find the NET-ENI config elsewhere. If CH0 is being used to pick up ASCII from a weigh module, let me know that too, on rung 0 of LAD 2.

For Logix5k, I tend to go with a structure that puts the abbreviated area or section or station name up front, with a capitalization style like rdrast uses. I also will use underscores to split names from device id stuff, and I try to keep the names short, to keep from having to look at so much rung wrap.

 

[uptown47]

Always describe input devices states in their true condition

Yep. Completely agree.

Rung comments that restate the obvious are useless.

Disagree. In my humble, even though it might be quite easy to work out what a network is doing, it isn't as easy as just reading it in English. When you are trying to quickly get to the right part in the program to start fault finding it's easier to whizz through a few sentences written in English than to work through a few lines of code, even if the code is very simple.

I like to write Network comments as a sentence (i.e. capitalise the first letter and then lower case after that).

Symbols comments I do in all capitals.

Interface variables in the variable declaration table I do the same as I write scripting variables. Start with lowercase for the first word and then upper case after that i.e. motorStart, motorStop etc etc.

;-)

 

[TConnolly]

Tagnames - CamelCapsLikeThis
Rung and instruction comments are typed out exactly as I would type out a message here.

This.

Device tags are all CAPS and match the tags on the electrical drawings. When I add a description to a device tag I use an _ followed by camel caps - eg, PB0500_StartButton.

Locally scoped tags that are used within subroutines when parameters are passed are preceded by an underscore, eg _bLocalTag would be used in a subroutine for a tag to which a parameter is passed.

 

[Lancie1]

When you are trying to quickly get to the right part in the program to start fault finding it's easier to whizz through a few sentences written in English than to work through a few lines of code, even if the code is very simple.

I agree. If you want to keep someone from knowing WHAT YOU MEANT to do, then leaving off an explanation is the first step. After some revisions, your great logic may no longer work correctly and somebody will have to find out why. Just make it as paranoid, obscure, unexplained, and difficult to troubleshoot as possible. It might help keep your job (or they might throw your B@%Q# out first chance).

 

[The Plc Kid]

Good Stuff

 

[dmroeder]

Rung comment: Sentence form
Instructions: The first character of each word capitalized.
Tag Names: Same as instructions (StuffArray[x])

All caps drives me nuts. I think it's hard to look at. Our programs used to be all caps on everything though.

 

[kolyur]

I use ALL CAPS for everything. I like to keep my font size as small as possible, to minimize rung wrapping, and caps is just easier to read at those sizes. Lucida Console 10 point is my preference.

That said, I don't work much with Logix 5000 and its obscenely long tag names, which would probably benefit from upper and lowercase combinations.

 

[dskohio]

Rung comment: Sentence form
Instructions: The first character of each word capitalized.
Tag Names: Same as instructions (StuffArray[x])

All caps drives me nuts. I think it's hard to look at. Our programs used to be all caps on everything though.

Totally agree with this method and dislike of all CAPS.

 

[dmroeder]

Rung comment: Sentence form
Instructions: The first character of each word capitalized.
Tag Names: Same as instructions (StuffArray[x])

All caps drives me nuts. I think it's hard to look at. Our programs used to be all caps on everything though.

That being said, any comments (not matter how they are structured) is better than no comments, so I'll take what I get!

 

[gravedigger02]

Rung comment: Sentence form
Instructions: The first character of each word capitalized.
Tag Names: Same as instructions (StuffArray[x])

All caps drives me nuts. I think it's hard to look at. Our programs used to be all caps on everything though.

I agree.

 

[Rube]

?sO dOING iT lIKE tHIS wOULD bE wRONG

 

[dskohio]

?sO dOING iT lIKE tHIS wOULD bE wRONG

I think you left your CAP LOCK on....