On 2/28/18 6:34 PM, James Laskey wrote:
This is always a tough one. It's like when you're refactoring code... sometimes
you just want to clean up the next thing, and the next, and the next, until
you're off in the weeds.
Thanks Stuart. RE apinote, I was trying to follow the pattern of other older
method comments (Roman-style.) Comments/Javadoc in most of these older
classes are a mix of styles. Question: if you update/clean-up a method in an
older class, should you bring the comment/Javadoc up-to-date as well?
On the one hand, there's the prevailing rule of remaining consistent with other
stuff in the same file. On the other hand, if there are problems with other
stuff in the file, it often doesn't make sense to propagate the same error to
the new stuff you're adding, merely in order to remain consistent.
Sometimes it's reasonable just to include the other cleanups along with the
current changeset, if they're small enough and prove not to be too much of a
At other times, the cleanups will tend to overwhelm the main goal of this
changeset. In those cases, I'd suggest proceeding the "right way" for the stuff
being added, even if it means a hopefully temporary inconsistency with the rest
of the file. Then do the cleanup and consistency changes in a separate pass.
This requires a separate bug report, but that's not a big deal. Often, if it's
just javadoc stuff, it won't require regression tests. If the doc changes are
merely editorial (not specification) it doesn't even require a CSR. So pure
cleanup changes can proceed relatively quickly.