Good practise on comments when programming

Hello,

I would like to have some opinions on what people this is good practise when it comes to putting comments in their programs.

I have seen that people write in the comments-field of the network the dates when they revised the plc program. They put in dates and initials, as well as an explanation on the changes they made. Is this good practise?

It can get a bit messy when the network is filled with dates and initials of people who might not work in the company anymore, and it might make one loose focus on the main explanation on what the logic is doing.

On the other hand, for people having to edit a program of somebody else, it can be nice to know what modifications they did, and when...

What do you think should be in the comments-field of a network?

Thanks!
Brg
A

Big problem is what make sense to one person is confusion to another!

I summarize my code at the top of each section, or if there is a particular line I feel needs some explanation I'll add a quick one liner and explain more at the top. While this leads often to paragraphs at the top of each section of code, I think it's often better to have a known place to go for each thing, and then highlight the issues during the code to get rid of clutter. I date changes in the top as well.

On the other hand, my background is primarily C based, but I do this in my PLC code as well. Splitting things into sections usually means some spacing occurs.

Never feel bashful about documenting. It sounds like you're working with Siemens software, which I'm not completely familiar with, but in Allen-Bradley it's easy enough to turn off the rung comments if they become a bit distracting from the big picture. Obviously, it's much harder "turn on" documentation which was never there in the first place. Even if you can't turn it off, I would much rather have it there and be somewhat annoying, rather than not having and working blindly through the code.

when i worked for an oem, i used lots of rung documentation.

the boss told me that i spent to much time documenting the rungs, stop doing it.

the next program i wrote has very little rung comments, everyone loved it.

10 years later, wouldn't you know i had to debug that same program for a change. had to figure the program out again.

the little ab box for descriptions does wonders when you write the code, the rung comments allow for a much bigger description of the big picture.

pay me now, or pay me later.

regards,
james

Hi

A simple rule I use in ab is ever 4 rungs at most of code I add a comment.
In Siemens I normally do ever network if it's slc of function block but again in ladder ever 4 at most

This is just a rule I try to stick to and it works well for me

Donnchadh

I usually use the rung comment on the first rung of the main routine. It lists all edits/fixes by date with reason for edit/fix.
This comment is started after the equipment is running.

What do you think should be in the comments-field of a network?

Click to expand...

Write network or rung comments long enough to cover the subject, but not so long as to be boring.

As for the dates and revisions, with Allen Bradley RSLogix, you can also add revision notes with dates and initials for the entire program using two different methods. You can add Revision Notes that are attached to the program, and can be retrieved with "Edit, Revision Notes". Another way is to add Summay Info Comments when you save a program. These can be viewed anytime by selecting "File, Summary Info, Comments".

If I am modifying someone else's code, I will add date, my initials, company name..etc just to make it clear that I have altered another companies code from original, I'll add a brief description of the section I modified and why. Usually it took me a while to figure out what the heck I am changing, so I figure it might spare someone the hassle down the road. Usually these are systems where the original OEM/Integrator is out of the picture and who knows who will touch it next.

I comment practically every rung of code. It doesn't have to be a long comment, maybe just a few words worth of description, but they're commented nonetheless. It helps me when I have to come back to the code weeks, months or years later, and it helps the next person who has to work on the machine.

My thought is, if I get run over by a cement mixer, someone else is going to have to maintain that code. If I can make it easier, so much the better.


-rpoet

I'm going to give you all a tip that I've been using for more than 30 years. It has worked for me very well.

Write your comments 1st.

With that said. Keep your comments meaningful. Simple English. Similar to the rules of technical writing. When you call a subroutine indicate what is done in the routine. If it contains code for several pieces of equipment you should list them. Inside the subroutine you should not what routines call the routine and how (STI, Continuously, etc...). Also, don't forget the revision number of the subroutine and what you corrected.

Point descriptions should contain the parent equipment name (ie. A run motor coil should description should start with the motor name), area of the plant, what it does (in one line) and valid states (1=Alarm).

Finally, and this is probably the 2nd most important thing, keep your comments up-to-date.

Cheers,

(8{)} .)
(Yosi)

Comments should be like a mini-skirt... long enough to cover the essentials but short enough to keep your interest.

I tend to write a 'function' comment at the top of the function or function block (I work with Siemens primarily) outlining what the function does and anything of particular interest and then just add short Network titles to every Network. If I'm writing in STL then I add // comments before each short bit of statement list.

I find these comments help me out just as much as other people when I revisit code in the future.

;-)

uptown47 said:

Comments should be like a mini-skirt... long enough to cover the essentials but short enough to keep your interest.

Click to expand...

Signature material!

Stolen!!

First network: Full explanation what the block does, why it does what it does. Different versions are added to explain what has been added/changed, much like you have version updates on regular pc programs.

Network header contains what network does.

Then a // *text* underlined by ******* and some spaces to create different segments in the same network.

Similar to how uptown47 does it


Used to comment almost every line of code, but it became cumbersome.
Using symbolic names, which have their own comments, and giving the general flow of the program, should be enough to make people understand it. If they still don't, they have no bussiness trying to change/troubleshoot that program.