I think that something like checkstyle, PMD and FindBugs, and update the
contribution page asking contributors to review their changes before sending
PR's or patches would help.
It would be good to avoid replicating unnecessary policies in the web site
though. Like suggesting that we expect the contributor to use 80 columns. That
would mean that we would have to update the checktyle XML rule file and the web
site if we decided to use 120 or any other number. We can probably leave some
basic policies (no tabs, no unused imports, etc).
WDYT?
Bruno
From: A. Soroka <[email protected]>
To: "[email protected]" <[email protected]>
Sent: Wednesday, May 13, 2015 2:07 AM
Subject: Code policies
>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
