Can you add too many comments?

[ganutenator]

It better to have too many instead of not enough right?

 

[Robb B]

in the forum? In the PLC program? on the wiring diagrams? no, best to write down whatever you can think of. Never misundestimate the quality of the next person to come across your notes or handiwork.

 

[joseph_e2]

I probably make my drawings way too verbose, with catalog numbers, wire colors, basically everything I can think of to help the next guy (...or me in 5 years). Same thing with PLC code. The only way I can think of to have too many comments is if you're saving them in a PLC that's not quite big enough for the application. In that case, I'd say the best thing to do is upgrade the PLC...

 

[drbitboy]

It better to have too many instead of not enough right?

Yes, better too many than not enough.

TL;DR

But the quality of the comments is probably more important. If it takes a couple of paragraphs to explain what a rung or statement is doing, then maybe that code should be refactored and simplified, even if it means breaking logic up across several rungs/statements, so it's easier to see prima facie what the code is doing and the comment can simply state why, and only explain what if absolutely needed.

There is a lot of opinion about comments out there; a search for "code comment standards" will find some useful pages. There are probably several threads in this forum alone.

 

[ganutenator]

I tend to describe the intention/reasons behind the code.
+ a little humor.

(* The correct setup is to set the top sp to a lower value than the side
Before the change in code, This would correctly not shut off the lp pump and lp s.v. before the side was done.
I wounder if Tom took into consideration blowing the rest out w/ air.
I wonder if since this first code change if I am leaving the air on.

I am attempting to write code so you can make the side sp smaller than the top sp for some reason I don't remember.
Here goes. 2023-09-27 iso format in case A A Ron ever reads this. he he
*)

(* attempt at writing code to above comment*)
(*I was told that you can not add too many comments.
I would argue that I can. And I'm pretty sure people that know me would agree w/ that*)

IF Pass1PreEarlyTopEn AND Pass1PreEarlySideEn AND Pass1PreEarlyOffInchesSideSp >= Pass1PreEarlyOffInchesTopSp THEN
	Pass1EarlyOffNormal:= TRUE;
ELSE
	 Pass1EarlyOffNormal:= FALSE;
END_IF;

 

[Steve Bailey]

But the quality of the comments is probably more important.

No 'probably' about it. Quality and accuracy. If you put in a comment that says, ""he next four rungs...." and then during debugging, you find you need to add a fifth rung, be sure to edit the comment.
If you have a comment that says, "This rung scales the 4 - 20mA signal from the header pressure transducer to the range of zero to 50 PSI", and then you later change the transducer to a zero to 60 PSI model, when you change the scale factor in the logic, be sure to change you comment text.

 

[James Mcquade]

years ago i was told that i need to stop using rung comments and use tag descriptions is a slc 500 program. so i did. everyone thought it was the best program i ever wrote. 2 years and 50 programs later, i had to look at the program again to make a modification. VERY Frustrating with no rung comments !! Never made that mistake again !
rung descriptions written to describe the process and what happens can never be to long or omitted. i left the company and they got a call to modify the program again. it took them a long time to figure it out. i was at another job and at a customers site for several weeks when they called for help.
james

 

[I_Automation]

I have had one customer that didn't want his program clustered up with comments.


I have 2 copies of that program. The first I go online with has all the comments I need to know what I was thinking then, the second I downloaded to a SLC and then uploaded creating a new file without comments and he gets that one.


If I have to do any edits I do them in my commented file and save them, then go online in his file uploading the usage file.


I have gotten into programs I wrote years ago without enough comments and couldn't remember what I was doing

 

[JeremyM]

I tend to describe the intention/reasons behind the code.
+ a little humor.

(* The correct setup is to set the top sp to a lower value than the side
Before the change in code, This would correctly not shut off the lp pump and lp s.v. before the side was done.
I wounder if Tom took into consideration blowing the rest out w/ air.
I wonder if since this first code change if I am leaving the air on.

I am attempting to write code so you can make the side sp smaller than the top sp for some reason I don't remember.
Here goes. 2023-09-27 iso format in case A A Ron ever reads this. he he
*)

(* attempt at writing code to above comment*)
(*I was told that you can not add too many comments.
I would argue that I can. And I'm pretty sure people that know me would agree w/ that*)

IF Pass1PreEarlyTopEn AND Pass1PreEarlySideEn AND Pass1PreEarlyOffInchesSideSp >= Pass1PreEarlyOffInchesTopSp THEN
	Pass1EarlyOffNormal:= TRUE;
ELSE
	 Pass1EarlyOffNormal:= FALSE;
END_IF;

Variable naming can go far in self-documenting code.

What is a Pass1PreEarlyOffInchesSideSp?

 

[robertmee]

Yes, better too many than not enough.

TL;DR

But the quality of the comments is probably more important. If it takes a couple of paragraphs to explain what a rung or statement is doing, then maybe that code should be refactored and simplified, even if it means breaking logic up across several rungs/statements, so it's easier to see prima facie what the code is doing and the comment can simply state why, and only explain what if absolutely needed.

There is a lot of opinion about comments out there; a search for "code comment standards" will find some useful pages. There are probably several threads in this forum alone.

Agree on the paragraphs, although I have a single CPT statement that's part of a linearizatuon routine of a 20x200 matrix that shows all the math in the comments...its a good 2 paragraphs

 

[drbitboy]

Agree on the paragraphs, although I have a single CPT statement that's part of a linearizatuon routine of a 20x200 matrix that shows all the math in the comments...its a good 2 paragraphs

Agreed. There are exceptions to every "rule."

 

[OkiePC]

Generally no, but I don't need a paragraph to describe a one shot storage bit.

My pet peeve with excessive rung comments is when they're on every rung and simply state the same info that can be gleaned from reading the rung.

Describe the "why" or the overall methodology, or a date, time and reason for an edit. Spell out a formula for a complex computation. Things like that which add context to the logic or explain the structure are invaluable and never too much.

 

[dmroeder]

Generally no, but I don't need a paragraph to describe a one shot storage bit.

My pet peeve with excessive rung comments is when they're on every rung and simply state the same info that can be gleaned from reading the rung.

Describe the "why" or the overall methodology, or a date, time and reason for an edit. Spell out a formula for a complex computation. Things like that which add context to the logic or explain the structure are invaluable and never too much.

Well said.

 

[ojz0r]

I read somewhere that you shouldnt explain what you do in comments, but why you do it.
This implies that the code should be so simple that the function is clear to the reader.




Edit: OkiePC said it before. Damn it, i could have sworn i read all comments before pressing "post reply" button.

 

[joseph_e2]

In general, what's happening should be clear, but I definitely explain the source of any "magic math" factors or ratios. Ideally, if I'm calculating a speed setpoint for example, I'll include every step, with tags, so it's obvious what's happening. Like, sheave/gear diameters, etc. are there as tags so it's crystal clear what to change if a sheave or timing cog is replaced later.
I'll also leave a comment explaining why a particular bit is present if it's not super obvious. Like, "Bit X is here to prevent Y from happening".