commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <seb...@gmail.com>
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 <joerg.schaible@scalaris.com> 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.

+1

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: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message