Chief Delphi - Thoughts On Comments In Team Code

Page 1 of 2

Show 100 post(s) from this thread on one page

Chief Delphi (http://www.chiefdelphi.com/forums/index.php)

- Programming (http://www.chiefdelphi.com/forums/forumdisplay.php?f=51)

- - Thoughts On Comments In Team Code (http://www.chiefdelphi.com/forums/showthread.php?t=144554)

King Nerd III

23-02-2016 17:37

Thoughts On Comments In Team Code

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.

Alex Webber

23-02-2016 17:40

Re: Thoughts On Comments In Team Code

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

23-02-2016 17:50

Re: Thoughts On Comments In Team Code

Quote:

Originally Posted by Alex Webber (Post 1545337)

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 :P

Foster

23-02-2016 17:52

Re: Thoughts On Comments In Team Code

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

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



        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

Code:

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); 

}

SamCarlberg

23-02-2016 17:54

Re: Thoughts On Comments In Team Code

Quote:

Originally Posted by Alex Webber (Post 1545337)

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

Alex Webber

23-02-2016 17:55

Re: Thoughts On Comments In Team Code

Quote:

Originally Posted by cadandcookies (Post 1545346)

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

Oops. Should have been comments. Spell check lol.

kylelanman

23-02-2016 17:59

Re: Thoughts On Comments In Team Code

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

23-02-2016 19:30

Re: Thoughts On Comments In Team Code

Quote:

Originally Posted by Foster (Post 1545351)

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



        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

Code:

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!

King Nerd III

23-02-2016 19:32

Re: Thoughts On Comments In Team Code

Quote:

Originally Posted by kylelanman (Post 1545358)

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!

King Nerd III

23-02-2016 19:34

Re: Thoughts On Comments In Team Code

Quote:

Originally Posted by Alex Webber (Post 1545337)

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!

Alan Anderson

24-02-2016 10:03

Re: Thoughts On Comments In Team Code

Quote:

Originally Posted by King Nerd III (Post 1545335)

Code:

        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

}

Ewww.

Seriously, don't do that. Comments that merely echo the code are distracting at best. They can actually be confusing and counterproductive, as they can give the reader the impression that the author is trying to explain something unobvious about what the code is doing.

Keep putting the "block comments" at the beginning of sections, explaining what the code is for, and explain assumptions and possible side effects, but don't overdo the line-by-line commentary on what the code does. You can better document that kind of information by choosing appropriately detailed and helpful names for functions/methods and variables. For example, instead of the abbreviated fl_motor, make the reader's job easier by calling it front_left_motor. Instead of left_speed, be more explicit with left_speed_desired or left_drive_commanded. That way it is obvious that you're not talking about left_speed_measured or left_intake_commanded.

MrRoboSteve

24-02-2016 11:00

Re: Thoughts On Comments In Team Code

Our coding guidelines at work say this about comments:

Quote:

Consider using code comments to document code whose operation is not self-evident to the professional developer (e.g. code reviewer). For example, consider commenting:

Pre-conditions not evident in code, e.g. thread-safety assumptions
Complex algorithms
Complex flow of control, e.g. chained asynchronous calls
Dependencies on global state
Security considerations

Avoid using comments that repeat self-commenting information found in many code structures. For example, do not add vacuous comments such as "Constructors", "Properties", "Using Statements". Avoid commenting:

Type declarations (e.g. method signatures)
Method overloads
Well-understood patterns (e.g. enumerators)
Clean code

You would get these code review comments on your method:

Document purpose of method and parameters
Rename fl_motor to front_left_motor, etc.
Input to the method should be in the orientation of the driver, and translated to motor inputs here. This means you'd negate the right value where it's used to set motor speeds
Use "- right_speed" rather than "right_speed - 1"
"Left Speed" should be "Left Drive Speed", etc.

After those changes, the method would look like this:

Code:

/**

 * Operate the drive base using tank-style control, where a joystick is

 * assigned to each side of the robot and independently controls its speed.

 * @param left_speed Desired speed of left side of robot

 * @param right_speed Desired speed of right side of robot.

 **/

void DriveBase::DriveTank(float left_speed, float right_speed){

        front_left_motor->Set(left_speed); 

        back_left_motor->Set(left_speed);



        // Right motors operate in opposite direction of left, so we negate

        // the values here to maintain the correct orientation.

        front_right_motor->Set(-right_speed); 

        back_right_motor->Set(-right_speed);



        SmartDashboard::PutNumber("Left Drive Speed", left_speed);

        SmartDashboard::PutNumber("Right Drive Speed", -right_speed);

}

Al Skierkiewicz

24-02-2016 11:08

Re: Thoughts On Comments In Team Code

From one who is not a programming person, comments are akin to the "show all your work" direction for math problems. However, when writing consider your audience.

King Nerd III

24-02-2016 11:29

Re: Thoughts On Comments In Team Code

Quote:

Originally Posted by Al Skierkiewicz (Post 1545926)

From one who is not a programming person, comments are akin to the "show all your work" direction for math problems. However, when writing consider your audience.

That's always been my approach to comments. I like to have every part of my thinking written out for me to review later, just like in math class.

Knufire

24-02-2016 11:40

Re: Thoughts On Comments In Team Code

I'd echo what Alan said. Using clear variable names and avoiding confusing syntax is better practice than over commenting within code. Definitely have everything documented in Java Docs if you're using Java though.

All times are GMT -5. The time now is 06:10.

Page 1 of 2

Show 100 post(s) from this thread on one page