On 2/28/18 6:34 PM, James Laskey wrote:
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?
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.

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 distraction.

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.


Reply via email to