From comments on some "clean up" PRs I submitted over this past weekend, it
seems that it would be nice to have some rough code standards that could help
newcomers _without_ inhibiting anyone from contributing. Possible policies that
came up included:
• Don't give a method signature that throws checked exceptions that
aren't ever thrown from the code in that method unless an API supertype specs
it.
• Don't leave unused imports in. Any IDE can solve that problem with
one keystroke. {grin}
• If a type declares a supertype that isn't a required declaration,
consider whether that clarifies or confuses the intent. The former is okay, the
latter not so good.
• Minimize the compiler warnings your code throws up. If you use
@SuppressWarnings to hide them, please add a comment explaining the situation
or a TODO with a potential future fix that would allow removing the suppression.
• Remove unused local variables or fields or uninteresting unused
private methods. If it's debugging detritus, consider replacing it with good
logging code for future use, if that seems likely to become useful.
• If there is valuable code in some unused private method, add a
@SuppressWarnings with an explanation of when it might become useful. If there
is valuable but "dead" code inside a "live" method, consider breaking it out
into a private method and adding a @SuppressWarnings and an explanation.
If we can develop a reasonable list of expectations for contributions (and
presumably, for the current code base) I will be happy to write some text for
project site pages and try to encode some of the expectations with Maven
Checkstyles. To be clear, I'm not suggesting any kind of blocking step in the
build process, just a chance for some handy feedback about code submissions.
Thoughts?
---
A. Soroka
The University of Virginia Library
