Go to Post Boy, am I ever glad we decided not to use eggs as game pieces like I originally suggested... - dlavery [more]
Home
Go Back   Chief Delphi > Technical > Programming
CD-Media   CD-Spy  
portal register members calendar search Today's Posts Mark Forums Read FAQ rules

 
Closed Thread
Thread Tools Rating: Thread Rating: 6 votes, 5.00 average. Display Modes
  #16   Spotlight this post!  
Unread 24-02-2016, 11:44
Caleb Sykes's Avatar
Caleb Sykes Caleb Sykes is offline
Registered User
FRC #4536 (MinuteBots)
Team Role: Mentor
 
Join Date: Feb 2011
Rookie Year: 2009
Location: St. Paul, Minnesota
Posts: 1,059
Caleb Sykes has a reputation beyond reputeCaleb Sykes has a reputation beyond reputeCaleb Sykes has a reputation beyond reputeCaleb Sykes has a reputation beyond reputeCaleb Sykes has a reputation beyond reputeCaleb Sykes has a reputation beyond reputeCaleb Sykes has a reputation beyond reputeCaleb Sykes has a reputation beyond reputeCaleb Sykes has a reputation beyond reputeCaleb Sykes has a reputation beyond reputeCaleb Sykes has a reputation beyond repute
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.
  #17   Spotlight this post!  
Unread 24-02-2016, 12:25
aeastet aeastet is offline
Programming Mentor
AKA: Tim Easterling
FRC #6043 (Allegan Tigers Robotics)
Team Role: Coach
 
Join Date: Jan 2015
Rookie Year: 2011
Location: Holland, MI
Posts: 123
aeastet is an unknown quantity at this point
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.
  #18   Spotlight this post!  
Unread 24-02-2016, 12:37
virtuald's Avatar
virtuald virtuald is offline
RobotPy Guy
AKA: Dustin Spicuzza
FRC #1418 (), FRC #1973, FRC #4796, FRC #6367 ()
Team Role: Mentor
 
Join Date: Dec 2008
Rookie Year: 2003
Location: Boston, MA
Posts: 1,079
virtuald has a brilliant futurevirtuald has a brilliant futurevirtuald has a brilliant futurevirtuald has a brilliant futurevirtuald has a brilliant futurevirtuald has a brilliant futurevirtuald has a brilliant futurevirtuald has a brilliant futurevirtuald has a brilliant futurevirtuald has a brilliant futurevirtuald has a brilliant future
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
__________________
Maintainer of RobotPy - Python for FRC
Creator of pyfrc (Robot Simulator + utilities for Python) and pynetworktables/pynetworktables2js (NetworkTables for Python & Javascript)

2017 Season: Teams #1973, #4796, #6369
Team #1418 (remote mentor): Newton Quarterfinalists, 2016 Chesapeake District Champion, 2x Innovation in Control award, 2x district event winner
Team #1418: 2015 DC Regional Innovation In Control Award, #2 seed; 2014 VA Industrial Design Award; 2014 Finalists in DC & VA
Team #2423: 2012 & 2013 Boston Regional Innovation in Control Award


Resources: FIRSTWiki (relaunched!) | My Software Stuff
  #19   Spotlight this post!  
Unread 24-02-2016, 13:04
cjl2625's Avatar
cjl2625 cjl2625 is offline
apel py
AKA: Cory Lynch
FRC #2067 (Apple Pi)
Team Role: Programmer
 
Join Date: Jan 2013
Rookie Year: 2013
Location: Guilford, CT
Posts: 412
cjl2625 is a splendid one to beholdcjl2625 is a splendid one to beholdcjl2625 is a splendid one to beholdcjl2625 is a splendid one to beholdcjl2625 is a splendid one to beholdcjl2625 is a splendid one to beholdcjl2625 is a splendid one to beholdcjl2625 is a splendid one to behold
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.
__________________
Head Programmer / Driver

Last edited by cjl2625 : 24-02-2016 at 13:09.
  #20   Spotlight this post!  
Unread 24-02-2016, 13:19
Daniel_LaFleur's Avatar
Daniel_LaFleur Daniel_LaFleur is offline
Mad Scientist
AKA: Me
FRC #2040 (DERT)
Team Role: Engineer
 
Join Date: Apr 2005
Rookie Year: 2003
Location: Peoria, IL
Posts: 1,967
Daniel_LaFleur has a reputation beyond reputeDaniel_LaFleur has a reputation beyond reputeDaniel_LaFleur has a reputation beyond reputeDaniel_LaFleur has a reputation beyond reputeDaniel_LaFleur has a reputation beyond reputeDaniel_LaFleur has a reputation beyond reputeDaniel_LaFleur has a reputation beyond reputeDaniel_LaFleur has a reputation beyond reputeDaniel_LaFleur has a reputation beyond reputeDaniel_LaFleur has a reputation beyond reputeDaniel_LaFleur has a reputation beyond repute
Send a message via MSN to Daniel_LaFleur
Re: Thoughts On Comments In Team Code

Quote:
Originally Posted by cjl2625 View Post
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.
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.
__________________
___________________
"We are not now that strength which in old days moved earth and heaven; that which we are, we are;
One equal temper of heroic hearts, Made weak by time and fate, but strong in will
To strive, to seek, to find, and not to yield. "
- Tennyson, Ulysses
  #21   Spotlight this post!  
Unread 24-02-2016, 13:27
Alan Anderson's Avatar
Alan Anderson Alan Anderson is offline
Software Architect
FRC #0045 (TechnoKats)
Team Role: Mentor
 
Join Date: Feb 2004
Rookie Year: 2004
Location: Kokomo, Indiana
Posts: 9,113
Alan Anderson has a reputation beyond reputeAlan Anderson has a reputation beyond reputeAlan Anderson has a reputation beyond reputeAlan Anderson has a reputation beyond reputeAlan Anderson has a reputation beyond reputeAlan Anderson has a reputation beyond reputeAlan Anderson has a reputation beyond reputeAlan Anderson has a reputation beyond reputeAlan Anderson has a reputation beyond reputeAlan Anderson has a reputation beyond reputeAlan Anderson has a reputation beyond repute
Re: Thoughts On Comments In Team Code

Quote:
Originally Posted by aeastet View Post
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.

Quote:
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
Code:
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.
  #22   Spotlight this post!  
Unread 24-02-2016, 13:32
Unsung FIRST Hero
Karthik Karthik is offline
VEX Robotics GDC Chairman
no team
Team Role: Mentor
 
Join Date: Apr 2002
Rookie Year: 1998
Location: Toronto, Ontario, Canada
Posts: 2,346
Karthik has a reputation beyond reputeKarthik has a reputation beyond reputeKarthik has a reputation beyond reputeKarthik has a reputation beyond reputeKarthik has a reputation beyond reputeKarthik has a reputation beyond reputeKarthik has a reputation beyond reputeKarthik has a reputation beyond reputeKarthik has a reputation beyond reputeKarthik has a reputation beyond reputeKarthik has a reputation beyond repute
Re: Thoughts On Comments In Team Code

Quote:
Originally Posted by Alan Anderson View Post


I have seen code with too many comments. It was like
Code:
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.
__________________
:: Karthik Kanagasabapathy ::
"Enthusiasm is one of the most powerful engines of success. When you do a thing, do it with all your might. Put your whole soul into it. Stamp it with your own personality. Be active, be energetic, be enthusiastic and faithful and you will accomplish your object. Nothing great was ever achieved without enthusiasm" -- R.W. Emerson
My TEDx Talk - The Subtle Secrets of Success
Full disclosure: I work for IFI and VEX Robotics, and am the Chairman of the VEX Robotics and VEX IQ Game Design Committees
.
  #23   Spotlight this post!  
Unread 24-02-2016, 13:38
GreyingJay GreyingJay is offline
Robonut
AKA: Mr. Lam
FRC #2706 (Merge Robotics)
Team Role: Mentor
 
Join Date: Mar 2015
Rookie Year: 2015
Location: Ottawa, Canada
Posts: 783
GreyingJay has a reputation beyond reputeGreyingJay has a reputation beyond reputeGreyingJay has a reputation beyond reputeGreyingJay has a reputation beyond reputeGreyingJay has a reputation beyond reputeGreyingJay has a reputation beyond reputeGreyingJay has a reputation beyond reputeGreyingJay has a reputation beyond reputeGreyingJay has a reputation beyond reputeGreyingJay has a reputation beyond reputeGreyingJay has a reputation beyond repute
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"
  #24   Spotlight this post!  
Unread 24-02-2016, 14:11
BrianAtlanta's Avatar
BrianAtlanta BrianAtlanta is offline
Registered User
FRC #1261
Team Role: Mentor
 
Join Date: Apr 2014
Rookie Year: 2012
Location: Atlanta, GA
Posts: 70
BrianAtlanta has a spectacular aura aboutBrianAtlanta has a spectacular aura about
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.
  #25   Spotlight this post!  
Unread 24-02-2016, 14:12
SteveGarward's Avatar
SteveGarward SteveGarward is offline
Red 5, standing by...
AKA: 7 years already
FRC #0111 (WildStang), FRC #3132 (Thunder Down Under)
Team Role: Mentor
 
Join Date: Dec 2009
Rookie Year: 2010
Location: Gurnee, IL
Posts: 173
SteveGarward has much to be proud ofSteveGarward has much to be proud ofSteveGarward has much to be proud ofSteveGarward has much to be proud ofSteveGarward has much to be proud ofSteveGarward has much to be proud ofSteveGarward has much to be proud ofSteveGarward has much to be proud ofSteveGarward has much to be proud ofSteveGarward has much to be proud of
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...)
__________________
FRC Team 111 - WildStang (Mentor, Drive Coach)
FTC Team 7458 - Full Force! (Mentor, Coach)
FRC Team 3132 - Australia's FIRST FRC Team! (Holy crazy first year, Batman!)

  #26   Spotlight this post!  
Unread 26-02-2016, 11:29
MamaSpoldi's Avatar
MamaSpoldi MamaSpoldi is online now
Programming Mentor
AKA: Laura Spoldi
FRC #0230 (Gaelhawks)
Team Role: Engineer
 
Join Date: Jan 2009
Rookie Year: 2007
Location: Shelton, CT
Posts: 305
MamaSpoldi has a brilliant futureMamaSpoldi has a brilliant futureMamaSpoldi has a brilliant futureMamaSpoldi has a brilliant futureMamaSpoldi has a brilliant futureMamaSpoldi has a brilliant futureMamaSpoldi has a brilliant futureMamaSpoldi has a brilliant futureMamaSpoldi has a brilliant futureMamaSpoldi has a brilliant futureMamaSpoldi has a brilliant future
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!
__________________
Closed Thread


Thread Tools
Display Modes Rate This Thread
Rate This Thread:

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

vB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Forum Jump


All times are GMT -5. The time now is 20:35.

The Chief Delphi Forums are sponsored by Innovation First International, Inc.


Powered by vBulletin® Version 3.6.4
Copyright ©2000 - 2017, Jelsoft Enterprises Ltd.
Copyright © Chief Delphi