GitHub Code Comments

Technical Programming
1

Hello,

My team’s programmer and I have been using YouTube and GitHub to teach ourselves FRC programming. I wanted suggestions on which teams do a good job of providing comments with their code on GitHub. We want to learn why code works rather than just hoping that it does work.

2

It might help to include which language you’re looking for resources on.

3

It would be for java.

1 Like
4

Thank you for that. Yes, the language would be helpful lol.

5

Lots of great teams you’ll see won’t actually comment their code much at all. Usually, a method should be named self-descriptively, and any comment that is added would just be redundant. Good code attempts to avoid requiring comments to be readable. With that said, the WPILib docs do a good job explaining what WPILib code is doing, and an understanding of the language should take you the rest of the way.

If you’re curious about why you wouldn’t want comments describing everything, see Don't Write Comments - YouTube. It explains the concept very well.

4 Likes
6

The two biggest things I know on this front:

  1. Know the tools in the toolbox. What features does Java provide? How do basic variables, types, operations, classes, import statements, etc. all work?
  2. Know how to think in abstractions. Understanding everything about a single robot’s code works is intractable. Rather, you learn to think about your code in single layers at a time, analyzing how each “layer” interacts with those above and below it.

FWIW, when I am writing code, I use both of these simultaneously. I usually think about what I want to do without once considering the line of code to do it - I consider what I’m trying to accomplish, what calculations I need to do it, what the inputs to those calculations are and what the results ought to look like, all without writing a single line of code. I will make lists and diagrams on a whiteboard. I make sure, as best I can, i understand what I want to accomplish in a framework that is abstract from the specifics of Java.

Then and only then, I start using the resources I know (or googling the ones I don’t) for how to express that idea using Java itself. This also might mean picking off components from WPILib or other libraries to help express sub-parts of my idea.

Reading other people’s code works the same way - going through each file line-by-line in order is probably the worst way to understand it. Rather, start by just looking at folder and file names. It should give you some indication of "Oh, they have a thing to control their drivetrain (Drivetrain.java). Oh, they have something that bridges camera data from one place to another (CameraInterface.java). Then, dig into the top-most looking code (for FRC, probably Robot.java) See what things are initialized, how certain things are connected together, etc…

Again, know that you’ll never be able to keep the whole codebase in your head at once, so the goal is to bite off a small enough portion to think about at the same time (while ignoring everything else).

3 Likes
7

If you want to go even deeper, this is a great playlist of lectures from Uncle Bob, one of the founding fathers of the Agile and SOLID principals.

1 Like