Thoughts On Comments In Team Code

[King Nerd III]

I was busy rewriting my teams code today, just cleaning up some things and adding comments, and I realized that I tend to over comment things (at least in my opinion) when I write code for robotics. Upon realizing this, I decided that in reality, it's good that I over comment my code, as we always have some new programmers each year, and I think it's good for all the comments to be there so that they know what's going on and can hopefully learn how the code works so that they can then go and write it on their own. Here's a sample of the amount of comments I tend to write:

void DriveBase::DriveTank(float left_speed, float right_speed){
	//This method drives each side of the robot using set values
	//The values are not changed in any way
	//Since the right motors are opposite of the left motors, their values are inverted in the command
	//Because of this, when the speeds are output to the SmartDashboard we invert the inverted value
	fl_motor->Set(left_speed); //Sets the front left motor to the left speed
	fr_motor->Set(right_speed); //Sets the front right motor to the right speed
	bl_motor->Set(left_speed); //Sets the back left motor to the left speed
	br_motor->Set(right_speed); //Sets the back right motor to the right speed
	SmartDashboard::PutNumber("Left Speed", left_speed); //Puts the left speed on SmartDashboard
	SmartDashboard::PutNumber("Right Speed", right_speed * -1); //Puts the inverted right speed on SmartDashboard
}

So here's my question to you, the programmers on Chief Delphi: What's your opinion on commenting robot code? Should there be an insane amount of comments so that new kids understand what's going on, or do you prefer to live by the mantra always repeated to me, "good code should explain itself"?
Let me know what you guys think, I'm very interested in knowing your opinions on the subject.

[Alex Webber]

Our team doesn't put cmments inside our methods. We Java Doc our code, with easily explainable wording so others can understand what is going on.

During development we typically do, but we transfer to Java Docs sooner or later.

[cadandcookies]

Originally Posted by Alex Webber

Our team doesn't put code inside our methods.

I'm curious as to how you manage to do that and still have a functional robot

[Alex Webber]

Originally Posted by cadandcookies

I'm curious as to how you manage to do that and still have a functional robot

Oops. Should have been comments. Spell check lol.

[kylelanman]

I encourage the students to comment the 'why' not the 'what'. When students are writing code the 'what' should be obvious. If not then it should probably be re-written. Commenting 'why' something is done is much more useful to someone reading the code.

[King Nerd III]

Originally Posted by kylelanman

I encourage the students to comment the 'why' not the 'what'. When students are writing code the 'what' should be obvious. If not then it should probably be re-written. Commenting 'why' something is done is much more useful to someone reading the code.

That's a great idea, I'll keep that in mind. I think based off of your advice I'll start having kids comment their code in that way, but I'm going to keep writing my comments as I have been, because some kids like to learn by reading my code, which means I feel like they would benefit from seeing the 'what' along with the 'why'. Thanks for the input!

[Foster]

So I comment my code a lot, but I don't comment the obvious. Like setting the speed to the motors is pretty clear from the code. But I did change the variable names on the code to make it clear it was front_left and not f1. (See you looked to "is that a one or an L"). Same thing with the dashboard. The code is clear, so the "set the dashboard" comments don't add any value. A reminder about the inversion isn't needed since we saw the comment 7 lines before, but it's a little weird, so worth a comment.

And if this is where the drive speed is actually set then I'd do the speed inversion here. That way the entire stack on top is going Foward is positive (+) Reverse is negative (-) and does not need to do the "well the right motors need to be inverted" every place else. That would also get rid of the need to re-invert it back for the display. That would reduce some code complexity.

My 2 cents since you asked, your mileage WILL vary.

void DriveBase::DriveTank(float left_speed, float right_speed){
	//This method drives each side of the robot using set values
	//The values are not changed in any way
	//Since the right motors are opposite of the left motors, their values are inverted in the command
	//Because of this, when the speeds are output to the SmartDashboard we invert the inverted value

	front_left_motor->Set(left_speed); //Set the motor speeds
	front_right_motor->Set(right_speed);
	back_left_motor->Set(left_speed);
	back_right_motor->Set(right_speed);

	SmartDashboard::PutNumber("Left Speed", left_speed); 
	SmartDashboard::PutNumber("Right Speed", right_speed * -1); //inverted right speed to make the number positive on the display
}

And with the inversion done here

void DriveBase::DriveTank(float left_speed, float right_speed){
	//This method drives each side of the robot. Forward is positive speeds, reverse is negative speeds.
	//The values are not changed in any way
	//Since the right motors are opposite of the left motors, their values are inverted when we set them

	front_left_motor->Set(left_speed); //Set the motor speeds
	front_right_motor->Set(right_speed * (-1) );
	back_left_motor->Set(left_speed);
	back_right_motor->Set(right_speed * (-1) );

	SmartDashboard::PutNumber("Left Speed", left_speed); 
	SmartDashboard::PutNumber("Right Speed", right_speed); 
}

[King Nerd III]

Originally Posted by Foster

So I comment my code a lot, but I don't comment the obvious. Like setting the speed to the motors is pretty clear from the code. But I did change the variable names on the code to make it clear it was front_left and not f1. (See you looked to "is that a one or an L"). Same thing with the dashboard. The code is clear, so the "set the dashboard" comments don't add any value. A reminder about the inversion isn't needed since we saw the comment 7 lines before, but it's a little weird, so worth a comment.

And if this is where the drive speed is actually set then I'd do the speed inversion here. That way the entire stack on top is going Foward is positive (+) Reverse is negative (-) and does not need to do the "well the right motors need to be inverted" every place else. That would also get rid of the need to re-invert it back for the display. That would reduce some code complexity.

My 2 cents since you asked, your mileage WILL vary.

void DriveBase::DriveTank(float left_speed, float right_speed){
	//This method drives each side of the robot using set values
	//The values are not changed in any way
	//Since the right motors are opposite of the left motors, their values are inverted in the command
	//Because of this, when the speeds are output to the SmartDashboard we invert the inverted value

	front_left_motor->Set(left_speed); //Set the motor speeds
	front_right_motor->Set(right_speed);
	back_left_motor->Set(left_speed);
	back_right_motor->Set(right_speed);

	SmartDashboard::PutNumber("Left Speed", left_speed); 
	SmartDashboard::PutNumber("Right Speed", right_speed * -1); //inverted right speed to make the number positive on the display
}

And with the inversion done here

void DriveBase::DriveTank(float left_speed, float right_speed){
	//This method drives each side of the robot. Forward is positive speeds, reverse is negative speeds.
	//The values are not changed in any way
	//Since the right motors are opposite of the left motors, their values are inverted when we set them

	front_left_motor->Set(left_speed); //Set the motor speeds
	front_right_motor->Set(right_speed * (-1) );
	back_left_motor->Set(left_speed);
	back_right_motor->Set(right_speed * (-1) );

	SmartDashboard::PutNumber("Left Speed", left_speed); 
	SmartDashboard::PutNumber("Right Speed", right_speed); 
}

In my experience, it doesn't really change much if you have it in the method or the command, as either way it's just one or two * -1 somewhere in the code. The reason we do it this way is because it just makes things easier when calling it in different commands, but to each their own!

[SamCarlberg]

Originally Posted by Alex Webber

Our team doesn't put code inside our methods. We Java Doc our code, with easily explainable wording so others can understand what is going on.

During development we typically do, but we transfer to Java Docs sooner or later.

Javadoc explains what the method does and anything that's needed for it to work properly. It doesn't explain reasoning behind the logic inside, which is very unhelpful when trying to debug. It doesn't need to be as zealous as OP's example, but you should at least have comments explaining non-obvious code

[Caleb Sykes]

We use javadocs as much as we can. In addition, we usually add comments explicitly stating units of variables. Besides that, we occasionally add in comments explaining what a single line does, but this is rare.

Putting a comment on every single line is a waste of human resources and just clutters the code.

[aeastet]

There is no such thing as too many comments. You have to remember that you will not always be there to explain what you were thinking. The more comments the better chance for getting help or your code surviving after you are gone. I have never seen code with too many comments. I don't believe that is possible.

[virtuald]

I suggest this short reading for those who believe comments to be unnecessary: http://catb.org/esr/writings/unix-koans/prodigy.html

[Alan Anderson]

Originally Posted by aeastet

There is no such thing as too many comments. You have to remember that you will not always be there to explain what you were thinking.

Comments that tell what a block of code does are good, as long as they don't get into too much detail. Comments that describe why the code does something are important. Comments that explain how it works at a high level are fine.

But comments that just duplicate the code in paraphrase do not help, and they can actively hurt if they fall out of sync with programming changes.

I have never seen code with too many comments. I don't believe that is possible.

I have seen code with too many comments. It was like

ACHK  EQU *       ; check if ASCII input is a letter
      LDA CNV     ; get the configuration value in the accumulator
      SUB #64     ; subtract 64
      BLT SKIP2   ; skip if less than zero
      ...

The first line's comment is helpful, describing what the routine is intended to do. The rest of the line-by-line commentary adds absolutely no information. It serves only to clutter the source code.

[Karthik]

Originally Posted by Alan Anderson

I have seen code with too many comments. It was like

ACHK  EQU *       ; check if ASCII input is a letter
      LDA CNV     ; get the configuration value in the accumulator
      SUB #64     ; subtract 64
      BLT SKIP2   ; skip if less than zero
      ...

The first line's comment is helpful, describing what the routine is intended to do. The rest of the line-by-line commentary adds absolutely no information. It serves only to clutter the source code.

It added plenty of information for me. I would not have understood that snippet of code without the comments.

[King Nerd III]

Originally Posted by Alex Webber

Our team doesn't put cmments inside our methods. We Java Doc our code, with easily explainable wording so others can understand what is going on.

During development we typically do, but we transfer to Java Docs sooner or later.

I'm thinking from a developmental and real world practicing standpoint, this practice would be great, but I'm more wondering about the teaching value of over commenting (if there is any). But I do think from a developmental standpoint I'm going to try to shift my team towards a more 'why' commenting system and less of a 'what', as I said to someone else on this thread. Thank you for your input!