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:
Code:
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.