Better commenting

[vmagro]

You should have comments on parts of code that people are likely to have difficulty understanding. Comments are also useful for yourself in the future, not just other people. Comments like the following are useless:

• all of the sensors and motor controllers
  • reader can tell in a second that this is where all of the variables are declared
• all the booleans for which drive is being used
  • again reader can tell instantly - this comment doesn't add any value
• the constructor
  • this is obviously the constructor
• initialize victors
• initialize Encoders
• initialize gyro
• change this to change threshold
  • I don't need the comment to know that if I change this I'm changing "the threshold", but what is it a threshold for?
• tells if gyro is a yay or nay
  • unnecessary, this is what booleans always do...
• the max angular velocity (duh)
  • I don't think I need to tell you why this comment is unnecessary (it says itself lol)
• max voltage for drive
  • what happens if it exceeds that? how is this used?
  • I had to read around 40 lines down to finally see that it's supposed to "stop drive if drive motors voltage exceeds a value"
• there is no comment at all in this section of the code, which is probably one of the more confusing bits
• negative because Vinnie did it
  • If I'm someone else reading this code, this doesn't help me figure out why it's inverted
  • It also indicates that you yourself don't know
  • The reason is because the motors on the left side have to spin in the opposite directions as the ones on the right in order for the wheels to go in the same direction. The polarity switch can be done in wiring as well, but some inspectors don't like that and it's generally bad practice to switch ground/power wires.
• This method takes when the equation returns above the max or below the min and fixes it so it does not. Uses some math and gets the job done
  • Again this indicates that you don't know what the code is doing. Maybe you do and you're just not explaining it well...
  • What this really does is "skim" a little of the power off the top of the left or right signal if they are above 1, so that if the driver is going really fast (with wheel speeds calculated above 1) they can still turn
• turns the solenoid on and off, dont call this method, use setgears
  • I'll revisit this comment in another issue, but asking people nicely not to call your method is a terrible idea :stuck_out_tongue:

I felt bad for giving so many bad examples so here are some examples of good comments (from your code):

• speed barrier for encoder, when encoder.getRate() exceeds this value, high gear automatically happens
• joystick is driven like a halo warthog, left joystick goes forward and backward, right joystick goes left and right
  • this should really be a javadoc comment, but the text it contains is good
• if ther joystick is not pressed enough, immeaditely stop, don't even do the math
  • other than the spelling mistakes, this is a good and descriptive comment
• this
  • again, should be a javadoc comment, but at least its descriptive