Not quite OT: 11 Rules All Programmers Should Live By

[ndzied1]

From the IT world but generic enough to apply to PLC programming as well.

http://simpleprogrammer.com/2015/03/16/11-rules-all-programmers-should-live-by/

 

[boneless]

So true!

I also have to keep in mind that the code looks different in my eyes than it does for my co-workers.

 

[adisharr]

Some good suggestions - I've found some of my old work hard to figure out when I revisit it a year (sometimes a few weeks) later.

 

[harryting]

4. Comments are evil.

Except this one. I can see why this would in the PC world though.

 

[ndzied1]

4. Comments are evil.

Except this one. I can see why this would in the PC world though.

Ya, this one is probably more applicable to Structured Text than Ladder.

 

[mk42]

Ya, this one is probably more applicable to Structured Text than Ladder.

The author makes an excellent point though: only the right kinds of comments are useful. When I was a brand new programmer, everyone told me I needed to comment more, so I did. I wrote in every comment box exactly what my code was doing: "If Input A or B are on, then turn on light C". I didn't understand why they still complained I wasn't commenting enough, couldn't they see everything I included?

What I learned is that the valuable comments tend to be the ones that explain WHY something is coded a certain way, not simply what it does. Comments that explain what the programmer was thinking are a lot better than comments that simply say what is going on. If you end up using what the author calls "clever code", good commenting can help your peers understand it and replace it later.

 

[Lancie1]

A guy that feels a compulsive need to go to the gym every Wednesday, could be wrong about comments too.

 

[Peter Nachtwey]

I will take issue with the minimizing writing code part.

Code must be added to handle the unexpected cases too!

Sure, minimize the code that needs to run but in the real world stuff happens. Good error handling and recovery routines are key.

34 years ago I was automating saw mill systems. There was constant pressure to make our machines run faster than the other guy's machines. However, piece count/rate wasn't all there was too it. Being able to handle wood going where it should go and being able to back up the queues to restart could make a BIG difference in production over the course of a day.

There are many threads on this site about keeping track of widgets on conveyors but what happens if a widget jams? Do you have to clear off the whole widget conveyor or can you back up the line and restart without losing any of the production on the conveyor?

In away this also reminds me of calculating MTBF, Mean time before failure.
In theory minimizing the number of parts on the board reduces the number of things to fail but there are good design practices that require putting protection devices like fuses or sacrificial resistors, diodes etc on the boards that will make recovery faster if something were to go wrong.

 

[wimpiesplc]

4. Comments are evil.

Except this one. I can see why this would in the PC world though.

Carefull with this one... might be S5/S7 trouble only but I have seen too many programs with comments all over the wrong place, rendering them pretty useless, from some up/download and not updating the source f*ckups

 

[OkiePC]

The author makes an excellent point though: only the right kinds of comments are useful. When I was a brand new programmer, everyone told me I needed to comment more, so I did. I wrote in every comment box exactly what my code was doing: "If Input A or B are on, then turn on light C". I didn't understand why they still complained I wasn't commenting enough, couldn't they see everything I included?

What I learned is that the valuable comments tend to be the ones that explain WHY something is coded a certain way, not simply what it does. Comments that explain what the programmer was thinking are a lot better than comments that simply say what is going on. If you end up using what the author calls "clever code", good commenting can help your peers understand it and replace it later.

+1

I don't need a translation verbatim of what the code says, I need a third perspective in the comments. Not what, but why?

A nice summary page of the "big picture" is priceless too. I don't care what language you are writing.

Matter of fact, I like to start writing code exclusively with comments in a text editor.

Then I divide and conquer in my native language, organize, outline, then each chunk gets broken down. Many of the comments that end up direct and simple translations will go away but the abstractions and overview explanations are always there.

In my world, I can toggle the comments off and on if they are too much of a clutter.

I agree with Peter too. Simplicity lends itself to versatility and reliability, but there is a minimum of reliability beyond which you should not strip down.