commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <>
Subject Re: [Math] Coding and documenting guidelines
Date Fri, 14 Jan 2011 00:21:24 GMT
On 13 January 2011 16:52, Jörg Schaible <> wrote:
> Hi Gilles,
> Gilles Sadowski wrote:
> [snip]
>>> Yes, though I don't see big problems with formatting and I don't see the
>>> need - and in fact see reasons not to - depart from the established
>>> standard or add more requirements that contributors need to follow.
>> There are no big problems, just a lot of small ones (e.g. using a keywords
>> like "null" without writing it as "{@code null}" and some comments being
>> complete sentences while others aren't).
>> If this is not important (again, I'm not saying it should be
>> high-priority), then I'd strongly suggest to remove the "trailing white
>> space" rule from CheckStyle because that one should be orders of magnitude
>> less important...
> There's a reason for such a rule. Most modern editors will remove them
> automatically, but when the original file contained such stuff, you end up
> with a diff that contains a lot of clutter (not to mention the fact that
> this diff might be a patch from JIRA and someone else has to apply it and
> might get as a result stupid conflicts).
> Obviously formatting changes will produce always such clutter and therefore
> it is important to clean up the source at least before a release, because
> you can expect patches against the tagged version.
> Annoying as a unified code format is for the individual developer, it
> improves maintenance a lot.


Also, trailing spaces can be trivially fixed automatically.

Changing null to {@code null} automatically is more of a challenge.


The most important objective for me is to ensure that the Javadoc is
complete and accurate.

Having a consistent style may help to make it more readable - or it
may not, if the style does not sit well with the reader.
I think it's far more important to ensure that committers are
encouraged provide the Javadoc, without having to worry about using
the correct "language".

> Just my 2¢
> Jörg
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message