Should You Comment Every Detail?

I always try to put a date on my comments. I think it helps.

Yeah, that alone can be quite frustrating. I've had the pleasure of reviewing some embedded C code that is filled with "2006 Nick" & "Sept 2021 Joe" at the beginning of code blocks. And that was it. No further documentation or usefully named variables. A fellow dev that has seen similar code calls it the fire hydrant method. Those devs piddle on the code and go about their merry way.
 
You can't over comment. Too many comments is like too much bacon or too much beer, not possible.

daba said:
I disagree, too much commenting largely gets unread. Many people will just scroll past it because they believe they can decipher "the code".

Phrog30, I think you used the wrong analogy, because as I agree with you that you can NEVER have too much bacon or beer, should of been below...

Phrog30/revisedGiT said:
You can't over comment. Too many comments is like too much spinach or too much broccoli, not possible.

I agree less is more, enough to get the point across...
 
I try to comment enough for myself to understand it if I come back months (or years) later. Nothing too wordy, just a simple explanation in a rung comment for every "section" of code, and aliased tags that are descriptive but not too long. I know I appreciate it, and I know that several of the plant guys that I've worked with appreciate it as well.



EDIT: I think this can sometimes also be achieved by "spelling out" the logic instead of using AOIs (that are on the simpler side anyways). I've used MUL and SUB instructions to do y=mx+b scaling instead of using a SCL AOI just for the sake of clarity, along with a rung comment explaining why.
 
Last edited:
If the P&ID is lost, then so is the process understanding. If it is lost, you're just screwed insofar as understanding.
 
' 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." '

This certainly seems unrealistic and basically just a bunch of fluff. "Tao" indeed. One could not have very complex code.
I make rung comments and descriptors in rs5000 for almost everything. And I will say I've gone back to older jobs just messing around and indeed wondered why I wrote something the way I did. The commenting helps me figure that out. And yes, I could've written it differently; everyone writes logic differently, however usually achieving the same result.
Lastly, I've gotten zero calls during the night or on weekends from my end users wanting to know what a certain part of the program did or meant or whatever. I've had many comments on how well my program is documented and how easy it is to understand some of my logic. Just sayin'.
 
Lastly, I've gotten zero calls during the night or on weekends from my end users wanting to know what a certain part of the program did or meant or whatever. I've had many comments on how well my program is documented and how easy it is to understand some of my logic. Just sayin'.


This is the biggest benefit. It's not a pain in the *** for you, and your customer doesn't resent you or think you're trying to hide or obfuscate anything. It's a win-win in my opinion.
 
If it hasn’t already been mentioned...

Self-documenting tag names are a big deal. You can have accurate and precise documentation, but if you just copy/pasted your MicroLogix code and named tags the “file” way, it’s still tough to get a handle on what’s going on with anything but the simplest code.
 
Phrog30, I think you used the wrong analogy, because as I agree with you that you can NEVER have too much bacon or beer, should of been below...



I agree less is more, enough to get the point across...


Too many good comments is not possible. Is that better? I sometimes forget there are people that just can't read between the lines on things. I'm assuming the comments are relevant and appropriate, not just useless info.
 
years ago, my boss told me that i commented to much as well as several others in a company.
so the 2400 rung program (12 subroutines) i wrote for that company had a lot fewer comments, everyone knew the process and what was going on. 5 years later, the process had to be modified. all the maintenance guys that knew the process has left and here i am looking at the program and struggling with what the code is because of the lack of my usual rung comments.
A word to everyone, just because you know the program inside out, upside down, and backwards today, doesn't mean you will remember the program 5 years later after you have written a hundred programs. i will NEVER make that mistake again !
james
 
A word to everyone, just because you know the program inside out, upside down, and backwards today, doesn't mean you will remember the program 5 years later after you have written a hundred programs. i will NEVER make that mistake again !
james
Let me echo that sentiment. Me too. Been there. I never find my detailed comments too detailed 5 years later. I figure comments aren't for others, they're for me.
 

Similar Topics

Hi, I am working on automating an industrial fabric shrinkage tester to replace its outdated electronics with a PLC. To get the tank's water level...
Replies
14
Views
501
In a control System, I need to move 3 motors attached to roller in stages with speed of 1 to 2 RPM and the torque of motor should be 8-10 Nm...
Replies
0
Views
816
Hi, I want to build a production line project using a PLC. This is the project page...
Replies
14
Views
2,058
See picture. I want to add a rung (magenta) into the existing code. Can't figure out how to do this. I select a -||- , right? When I drag/drop...
Replies
21
Views
1,690
Sorry for the basic question: On my HMI, I've created a button labelled SAVE to save the current values (distances in mm). It's not linked to any...
Replies
22
Views
2,132
Back
Top Bottom