We have 12 comments not including commented-out code, external libraries, and one todo. Our 12 comments are to explain the status frames but we do try to make the least amount of comments as we can and just make good naming
This is inspired by How many commits has your codebase had this year?
Not enough honestly. We did a pretty bad job commenting our code and a lot of it is hard to read.
1 Like
Good naming does go a long way in terms of readability, but comments are important because they provide additional context for how and why code was written the way it was. My team’s main repository has 23 inline comments and about 100 Javadoc comments, and the offseason repository comment count is increasing every day.
Particularly speaking about the offseason repository, each non-trivial (i.e. not a getter or setter) function has a Javadoc annotation explaining the purpose of the function. Single-line comments with links to documentation or other projects are also common. For example, the swerve implementation borrows concepts from YAGSL, so that repository is linked to whenever it is used as a reference.
2 Likes
Not enough.
2 Likes
we did not have enough, at all. we tried establishing a style guide this year but ended up not going through with it fully, had inconsistent and borderline messy code x)
I get the need for comments to explain the context, but if you extract that part into a method with a name that explains the context it solves that issue, and in my opinion, it makes everything look better
But javadocs are very important
1 Like
We have 33 inline comments and 25 javadoc method descriptions this year, for a total of 58 comments
My feeling on code comments is that they should be an exception, rather than a rule. Most of the readability should come from naming and architecture.
Use a comment when a line of code is fundamentally confusing. Do not use a comment when a line of code is doing something ordinary, but there’s not enough context to understand what - instead, refactor the code until the ordinary thing looks, well, ordinary.
7 Likes
Every public function has javadoc for all our packages and libraries so that’s around 3-400?
Are we counting javadocs as comments? Hrm…
I mean how many non-javadoc comments does a code base really have?
I wouldn’t consider javadocs as comments
1 Like
It depends, but i’d expect more than zero.
Then I’ve got like nothing, since anything that would be a comment became properly formatted and explained javadocs, I think there’s like one like that says do not move or it will crash because of some funny instantiation orders.
1 Like
No TODOs, even?
They got done, there’s two to dos over checking if my math was right for something but that’s about it, can’t just let the todos sit around
2 Likes
At 5990 our philosophy is that comments are bad, as they usually rot, as Uncle Bob likes to mention in many of his lectures. Instead, we opt for better method names and more methods in general in order to include the words that could have been in a comment as part of the actual code.
To be clear, comments are not documentation/javadoc, those are different things. I am talking about comments with the purpose of explaining how and why the code does what it does.
The number of comments currently in our code base is 12, excluding commented-out code, copy pasta such as the PV PoseEstimator, and 1 TODO.
These 12 are all one after the other, where we set some status frames, to describe each frame and what it contains.
I’d love to hear yall’s thoughts about this approach and what approach you have at your own team.
Note:
I’m OP’s lead
4 Likes
I think this a fantastic approach, javadoc ties to things and is key for understanding, but regular comments get left behind and end up out of date and can be more confusing then they are helpful after a while if n or being updated with the code.
2 Likes
