Should You Comment Every Detail?

Direct quoting from:

https://www.plcacademy.com/structured-text-tutorial/


"As you gradually get better and better, you should make fewer and fewer comments about the functionality"


and original is
http://www.mit.edu/~xela/tao.html





2.4

A novice asked the Master: "Here is a programmer that never designs, documents or tests his programs. Yet all who know him consider him one of the best programmers in the world. Why is this?"
The Master replied: "That programmer has mastered the Tao. He has gone beyond the need for design; he does not become angry when the system crashes, but accepts the universe without concern. He has gone beyond the need for documentation; he no longer cares if anyone else sees his code. He has gone beyond the need for testing; each of his programs are perfect within themselves, serene and elegant, their purpose self-evident. Truly, he has entered the mystery of Tao."






I disagree this. Code should be easy to understand but it don't mean that commenting isn't needed.
Years after it is lot of easier than trying to read even own code and rethinking why it is coded like it is.


What others think of this?

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


While tag based programming has allowed me to let up a little on the comments as the tags will sometimes speak to what your trying to do. I still comment a lot and as I said no one's ever said it's to much.

Absolute tosh.

While not promoting them in the PLC context, rather to add ideas to the discussion, I submit the style rules for comments in the Linux kernel; that is a very (i.e. C), but in some ways not so much (real-time), different environment.

N.B. the middle paragraphs, about the format detail of comments, would not apply to ladder, though perhaps to ST.

According to that, I over-comment.

Summary

• Comment WHAT, possibly WHY, never HOW.
  • "It's a waste of time to comment badly written code."
• Comment groups of rungs (functions), not individual rungs (lines).
• It's important to comment data.

Try to write code, so it self explanatory.
At beginning of program/procedure/function define what is it's goal and method of achieving it.
It is important to name labels according to some system and comment it.
Use structured data types.
Make good organization of program.

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.

Ha Ha
If it was hard to write, it should be hard to understand ;-)

I comment as needed. Not every line, but a lot. Since I often am writing for a customer, I want them to understand the logic well.

If everything important then nothing important.
That means not comment on every detail, should comment for only necessary.

I comment it as much as I can. Make it as understandable as possible for the tech trying to figure out what's wrong at 2AM on a Saturday night.

Comments, IMHO, have gained me repeated business for several of my clientele.

I read this years ago, so will start with an apology if it is in any way "inappropriate" ...

So, here goes, a quote by the great man Winston Churchill...

"A good speech should be like a woman's skirt; long enough to cover the subject and short enough to create interest."

Same goes for documentation and commenting....

I find it hilarious and relevant. Did not know Churchill had said something like that. He could not have imagined it could be applied to PLC programming.

AlfredoQuintero said:

I find it hilarious and relevant. Did not know Churchill had said something like that. He could not have imagined it could be applied to PLC programming.

Click to expand...

Perhaps he did not ....

https://quoteinvestigator.com/2018/04/20/short/

bob1371 said:

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

Click to expand...

+1

If you have ever had the experience of deconstructing someone else's poorly documented code you will forever after err on the side of "too many" comments.

There is no downside to lots and lots of comments.

Ye.

It doesn't matter how many comments there are if they are garbage, so it's quality rather than quantity, in saying that plenty of good & valid comments are useful to others.