-
Notifications
You must be signed in to change notification settings - Fork 611
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Document/Foolproof code #2441
Comments
Few read the regular documentation, even less read the javadocs. What you see in ChiefDelphi is a vastly small subsection of the FRC community. And I feel that the proposed solution is in vain. Perhaps a better solution would be better exposure for documentation in general? |
Although the docs should be more exposed, 99% of teams encounter the Javadoc as quick definitions of methods/classes. Adding to that docs should help prevent mistakes like these. However, having a "Rookie Mistakes" (probably use a different name, but the point is clear) page in the official online docs would be a great idea. |
I'm in favor of documenting these sorts of frequently encountered mistakes where possible. I'm against trying to magically fix mistakes for users. APIs should act the way they're documented. If users encounter issues, we should (subject to API compatibility constraints) update the APIs (and their docs) to address these. |
There are many posts on CD, etc. about "bugs" encountered by a simple human mistake (for example, scheduling a Command in the end() method of a command with overlapping requirements. This causes end() to be called infinitely. The correct use is using .andThen())
I suggest to document against mistakes like these (preferably in the Javadoc itself, saying what not to do and what to do instead. Another option is to try to foolproof code workings so mistakes like these work.
The text was updated successfully, but these errors were encountered: