Ch 9 intermediate programming: No javadoc in 'on comments' section?

[Declan-F]

I do not know how java works much, but from what I've heard java has a specific format for documentation known as Javadoc, which is supported by oracle. I think this would be very helpful to elaborate on in here, since IDEs like vscode typically support showing documentation of them on highlight. Moreover, with doxygen one should be able to convert Javadoc comments to HTML code, which can serve as github documentation for a project.

[Declan-F]

I reread the section, and I think I was a little confused with how comments are presented in this as well. I disagree with saying that you shouldn't have a comment for a function or variable. Sometimes variable names get annoyingly long if no documentation is used to explain them, and even when you are structuring your programming, it does not eliminate how functions build on each other, and the increased complexity that needs explanation as a result of that. I used to fall into the trap of spending 10 minutes naming my variables. At the same time, I also think that only using comments to make code understandable should be a last resort. I think that good naming and commenting code are both needed for making code easily readable. And if your code is ever commented too much, most IDEs allow for collapsing comments. Unusual exceptions aside, comments are useful to indicate broad decisions and reasons, but not necessarily specific details that are prone to change (unless commenting on edge cases).

Javadoc should still be useful and should probably be explained, since it allows for accessing documentation for functions without looking at the file with the function.

[mootw]

i agree that you shouldn't completely avoid comments, but most variables should be self descriptive, and only require comments for specific caveats like there is a range limit or a certain null behavior. i will definitely go over the section again to add more examples and clarify the verbiage. it shouldn't take 10 minutes to come up with a good enough descriptive name for a variable, that is a strong sign that your structure is bad and your variable does not belong. most of the code we write in FRC for the main robot drive is code that is quite self descriptive and comments are mostly used for explaining how it applies to hardware or other documentation like the name of an auto path.

as far as javadocs go, they can be quite useful, and i will definitely mention it in the docs, but for our usage, they will be minimally used. tpyically, javadocs are used in libraries and shared code where the implementation is abstracted away and needs comments explaining what it does; think of it as a header that explains what the code does. it is intentionally redundant and will go out of date. javadoc is also typically used for marking what exceptions a piece of code can throw (exceptions are not frequently used in frc code). if anything, we will be using null annotations and that will be something im going to look at implementing into our standard code. (kotlin provides null safety, but im unsure how easy we can switch to that without straying to far from stock frc tooling).