The importance of structure and comments!

I would like a discussion on programming structure and commenting.
This is more for the benefit of learners or people who have not done many full programs.

I have just recently had a horrendous experience where two separate contractors were engaged on the same project. (Well three actually if you count the electrical company who did all the wiring.)

The very short version:
A company I do work for bought some second hand plant. A concrete batching system and a block making machine.
I was given the batching plant to strip out and make a new control panel and the other company got the block making plant.

This project was ill conceived, miss-managed and a balls up from the start. The other company wanted my slice of the cake and I suppose I wanted there’s too.
The reason that two contractors were given the same project was for speed???
(If one does one half and the other, the other – it will be done twice as quick)

My panel started off with about 130 I/O (but ended up nearer 300) and a HMI Theirs was a similar number.
I was told that there would only be about 3 or 4 interconnecting signal cables between the two panels but the job got bigger and changed daily. We ended up with a 36 core cable between the two and every core is used.

To the crux of the matter:
The other company was eventually sacked before the end and I was left with both programs to finish. I am not being cruel or bitter, but the program I was left with from the others was the worst spaghetti code I have ever seen.

Page after page of internal bits with no comments or labels or anything to identify what they were doing.
Loads and loads of redundant code that should have been removed.
Lines with conditional branches after branches ( I bet even the plc itself struggled to understand what it was supposed to do)
Data manipulation that was meaningless with no particular order of registers.

The outputs and sequence was written in any random order – The first line was controlling output 85 (a small motor)
The emergency stops and safeties didn’t appear until about half way. I ended up just wiping reams of code and seeing what now didn’t work. It was very close to a re-write.

I wish I had the program on this computer; I would cut and paste a sample (I still might do tomorrow)
The point I am making is to all programmers really.

Please condition yourself to program into some sort of coherent order.

There are no set rules as to how you do this but it really helps (both you and followers to understand what is happening)

The first and most important rule is each time you do a line of code, label or comment each and every bit and add a description of what the program is doing. (even if it’s spaghetti, the comments will help)

I would like some input from the pro’s on how they structure their code. To help the learners start off on the right footing.

My way is (usually, that is – as nothing is written in stone here)
At the start a few lines of house-keeping (this is often written when the program is finished) ie resetting bits that might still be on after a power cycle. A first scan bit to put everything right and safe.
Then safety’s and E stops and the like.

Then the main program, hopefully with either the inputs or outputs in sequential order.
Then data manipulation. Ie math(s) and HMI values.

I often have none technical people look at my programs, and even they can understand what is supposed to happen.

I don’t think I can over emphasize the importance of keeping the code in order with written information all the way.

When it comes to programmers, Qualify before Quantity.

I learned long ago that it is best to pay twice as much more a single programmer than to pay for two. To assume twice as many programmers will write code twice as fast is an error but then you found that out the hard way. Coordinating two programmers is requires that they WANT to work together and there communication and cooperation. Without that the project is doomed, but Goody knows all about that.
To assume two companies can work twice as fast as one is insanity. They may come close under ideal conditions.

To do software most efficiently, each project should be done by ONE person or company. This makes it very important that the ONE programmer is extremely good.

It is also very important to have documentation on how the program is going to work and how each module is going to interface to other modules before starting. In the past when I was a one man show this was not very important but now it is a must. The initial specifications can also be reworked into the final manual.

"The reason that two contractors were given the same project was for speed???"

Whenever I see this kind of statement, I am reminded of the old joke "If it takes one woman nine months to have a baby, how long will it take two women?"

I always start out listing the major control loops of the system:

P1 Control
--Flow control
--Starting sequence
--Alarms
P2 Control
--Flow control
--Starting sequence
--Alarms
General system alarms
Data logging
Communications
etc. etc.

I assign subroutine numbers for each function.

I make sure I have an accurate point list of all the I/O.

I create a text description of the operator interface screens I plan on using so I know roughly how much data I need for each machine or control loop. For example, "Screen 5, Pump 1 status and aalrm bits, trend on flow vs. time" and "Screen 12, Pump 2 Tuning Setpoints, tiem delays, and alarm trip points."

Then I create conventions for nicknames: P1_RUN_OUTPUT, P2_MCC_FAUT, and so on.

Finally, I assign blocks of bits and registers for each group of functions: C100 to C127 for pump one status, V3200 to V3277 for Pump 2 alarm limits, T100 to T130 for Pump 1 alarm timers, and so on.

Then, when I start to write code, I can go down the lists and I have a basic structure for the program, as well as a clear picture of the functions I need to incorporate. Obviously, I never guess right 100% on the amount of bits and so on I'll need, but it at least creates a logical framework and I can easily go back and modify as I need to.

The more work you do BEFORE you start writing ladder logic, the easier the programming is.

"The more work you do BEFORE you start writing ladder logic, the easier the programming is."

I couldn't agree more. I am not a full time programmer, and so can be slightly rusty on the language itslef from time to time, let alone the program of any certain machine. From experience, documentation is not just important but CRITICAL. I was called recently to do a service call on a machine that I myself programmed when I first started. I had most of the bits named, but no line statements. Sure back then I could look at the ladder and see exactly what was happening, but a couple years down the road and it was a different story. Found myself saying "if I only I could find that bloody programmer.... oh yeah".
PLEASE document your programs!

A few hours work figuring out what bits are going to represent what and laying out how the program will be will more than pay for itself down the road. Also helps you debug along the way.

I'd second many other's comments here. My basic thinking on programming style is:

• Comments on every I/O address internal and external are a must!
• Rung comments should be used generally at the beginning of "sections" of code or for particularly detailed (potentially confusing) parts of code.
• Use all the features of your programming software to your advantage. For instance, import/export functions which let you setup comments and addressing schemes in a spread sheet or database. This can Greatly enhance a common look and feel to your program.
• Use the all the features of your processor to your advantage. For instance breaking up logical sub-systems in subroutines vs. one monster program. And use multiple data files (if available) instead of cramming all internal bits into one file. For instance, on A-B processors, I always put all my one shot bits in File B9 and that's all I use it for. On large projects, each sub-system can have its own bit file, integer file, float file, string file, counter file, timer file...
• Separate functions as much as possible. The most confusing code comes from seemingly unrelated physical devices which share code in the program. (Although this is sometimes necessary for machine functionality)
• Follow common templates for each subroutine in the program. For instance, if the outputs for subroutine 'A' appear first followed by the HMI code, don't reverse it in subroutine 'B'.
• Follow common naming conventions for address tags and aliases (Using a database or spread sheet helps here)

For me, there seems to be a 'critical mass' where a program gets split into separate subroutines. I can't cite a definate I/O or rung count but I guess a good rule of thumb woulb be when you, the programmer, start getting lost in your own program, break it up into subroutines.

These are just some basic guides I have stumbled along and learned the hard way and by no means the end-all be-all of programming. I'm anxiously awating the replys of others