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

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.

Re: Thoughts On Comments In Team Code
 

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

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:


And with the inversion done here

Re: Thoughts On Comments In Team Code
 

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

Re: Thoughts On Comments In Team Code
 

Oops. Should have been comments. Spell check lol.

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.

Re: Thoughts On Comments In Team Code
 

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!

Re: Thoughts On Comments In Team 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!

Re: Thoughts On Comments In Team Code
 

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!

Re: Thoughts On Comments In Team Code
 

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.

Re: Thoughts On Comments In Team Code
 

Our coding guidelines at work say this about comments:

You would get these code review comments on your method:

1. Document purpose of method and parameters
2. Rename fl_motor to front_left_motor, etc.
3. 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
4. Use "- right_speed" rather than "right_speed - 1"
5. "Left Speed" should be "Left Drive Speed", etc.

After those changes, the method would look like this:

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.

Re: Thoughts On Comments In Team Code
 

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.

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.

Re: Thoughts On Comments In Team Code
 

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.

Re: Thoughts On Comments In Team Code
 

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.

Re: Thoughts On Comments In Team Code
 

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

Re: Thoughts On Comments In Team Code
 

I add comments when it isn't totally clear what a piece of code is doing.
For that tank drive example, I wouldn't have any comments (aside from the negating one side thing, perhaps), since that code is pretty self-explanatory. Comments there seem redundant.

When there's too many comments, I find it bothersome and intrusive.

For single lines whose functions are unclear or confusing, it's worth a comment, but sometimes I neglect to do that (which is a bad habit of laziness).
And perhaps before each method or section of code, I'll sometimes add a line of explanation.

I suppose I'm guilty of sometimes being too cryptic in variable names and documenting my code poorly. Since I basically wrote all the team's code for the past 4 years, I've been able to get away with it, but it's a habit I should break.

Re: Thoughts On Comments In Team Code
 

You are not the target of your comments, the person behind you is the target.
What may be clear to you may be "clear as mud" to the one following you.

I suggest commenting every section, not line. And I suggest having someone whom is learning the language to try and interpret your code ... if they cannot then you need more comments.

Re: Thoughts On Comments In Team Code
 

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 seen code with too many comments. It was like 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.

Re: Thoughts On Comments In Team Code
 

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

Re: Thoughts On Comments In Team Code
 

Keep in mind that what's obvious to you today, in the heat of the moment, might not be obvious to you a few months from now, or worse, a few weeks from now, inside your pit, frantically trying to fix a bug.

Let alone the next programmer next year who inherits the code.

I agree that wading through "obvious code is obvious" comments are counterproductive.

Use useful variable names.

Use constant definitions wherever possible, and give them useful names. LEFT_SHOOTER_MAXIMUM_RPM is more clear than MAX.

If you have a lot of nested function calls, that you're doing math on, and casting to new types, all inside of a conditional, it helps to break all that out. Store some of the values inside of temporary variables and pass those into the conditional.

Ternary operator ? "Use it sparingly" : "Don't use it"

Re: Thoughts On Comments In Team Code
 

TLDR: FRC = OK, at a job usually not good.

I'll chime in on this. Realize that programming for FRC and programming as a job are somewhat different. In FRC, the method being called by the framework is Execute, IsFinished, etc. These methods names tend to not be very descriptive of what is attempting to be done, but you're not doing a lot in the method (5, 10, 15 lines of code). So, adding comments for why and not what your doing is generally always good. I did a code review with the development team on Monday and pointed out some minor things. I asked a the junior/rookie programmers about our vision code. There was a method called FilterContours. When they said what they thought it would do, I asked the developer, does it do that? He said, No. Yes from a low level your using contours, but from a business logic standpoint, using GetBestGoal would have made it better. I usually see nested ifs (Arrow Code Anti-pattern), Magic Numbers, and unclear variable names. I usually focus on those items in reviews.

In software jobs, comments are usually considered a Code Smell and indicate a different problem with the code. Typically the comments usually indicate a method has more than one responsibility and the method name doesn't explain what it's trying to do. Another indicator of same problem is that these commented methods usually higher line counts for the method. I'm working on code right now that the following functionality in a single method:

Convert text file to fixed width
Merge fixed width file results into temp file
update several fields
generate statistics

So, as you move to a different block of code, there's a comment. In a code review, I would kick that back. I would tell the developer to break out the commented sections as private methods and then the current method looks like above, instead of 150-200 lines of code. Oh, btw the class is used like the subsystems in FRC, being called by an engine calling methods on an interface. In this case all 150-200 lines of code are in a method called PostProcess.

Re: Thoughts On Comments In Team Code
 

I always encourage students (and trained professionals!) to think through their algorithm on paper/whiteboard, then put the algorithm steps into their code as comments, before writing code. The code then fills in between the comments. If your algorithm was right, your code should match. I find this better than simply commenting the code that was written after the fact - that doesn't make the algorithm right, it just means you understood what the code that was there was doing, enough to document it.

This also tends to lead to documenting the important steps in the code, not every line for the sake of it. Just like code, clarity, brevity, and correctness in comments are probably the most important factors.

(Comments in assembler are a different matter entirely...)

Re: Thoughts On Comments In Team Code
 

I agree with many of the others posts in this thread.

Here is my 2 cents:

• the level of commenting shown by the OP is excessive and not necessarily helpful as it clutters the code and does not really provide any added information;
• thoughtful comments on why something is done in the code is generally much more useful than what is being done;
• a caveat to the previous point: if the code is a bit complicated it can be very helpful to provide a comment that explains the algorithm being implemented at a higher level and/or any issues that were encountered when implementing it a different way that seemed simpler but didn't work;
• including comments with all constants being defined that state the units and how the constant was determined are very useful when making adjustments at competition;
• other coding standards such as using consistent and descriptive variable names and avoiding confusing syntax (e.g. trying to put too much into a single line of code), as this will make your life much less stressful when you are working on your code in the pit.

Good Luck!