checkstyle-5.5 online for xgc

[Glenn Adams <gl...@skynav.com>]

I've completed updating XGC to use the same checkstyle-5.5 configuration
that is currently being used with FOP (trunk). Because a number of XGC
files do not follow these style conventions, and would produce hundreds of
warnings were they to be imposed, I have in these cases selectively
disabled specific rules by inserting CSOFF declarations into the files. I
believe that is a better approach than making wide scale code changes to
significantly alter the originally authored conventions.

For moving forward, i.e., adding new files, we should endeavor to follow
the rules when acceptable. However, as a reminder, the goal of using
checkstyle is to improve coding consistency when there is general agreement
to use some convention. Nevertheless, there remain some style rules for
which there is not general agreement. In those cases, I would expect the
default (currently specified) rule to apply unless a particular developer
wishes to diverge from the default, in which case I have no problem with
using CSOFF/CSOK declarations as desired. Personally, I do not agree with a
number of the whitespace related (and other) style conventions that are
presently encoded in the default rules; as a consequence, I will likely
make use of CSOFF declarations in files that I author in order to disable
certain rules.

I view this use of checkstyle and style rule enforcement as a recommended,
but optional process that we developers agree to follow when we can do so
and when we agree. I am opposed to any view that would consider these rules
to be mandatory or absolute. We represent a community of diverse interests,
experiences, and preferences. Imposing a single set of rules in an absolute
manner would, IMO, be detrimental to creating a healthy, dynamic community
whose opinions do not always coincide. That being said, I think we should
also respect the styles used by specific authors; i.e., for cases where
there is not unanimous consent to use a specific style rule, we should not
change the styles used in a specific file simply because we don't like it.

For my part, I will henceforth run checkstyle and fix any reported warnings
before committing to XGC. I hope that other developers will do this as well.

Regards, Glenn

Re: checkstyle-5.5 online for xgc

[Glenn Adams <gl...@skynav.com>]

On Wed, Jun 6, 2012 at 8:37 AM, Chris Bowditch
<bo...@hotmail.com>wrote:

> On 03/06/2012 16:58, Glenn Adams wrote:
>
> Hi Glenn,
>
>
>  I've completed updating XGC to use the same checkstyle-5.5 configuration
>> that is currently being used with FOP (trunk). Because a number of XGC
>> files do not follow these style conventions, and would produce hundreds of
>> warnings were they to be imposed, I have in these cases selectively
>> disabled specific rules by inserting CSOFF declarations into the files. I
>> believe that is a better approach than making wide scale code changes to
>> significantly alter the originally authored conventions.
>>
>
> FYI: Vincent is on holiday this week. I expect he will have some feedback
> on this topic. In the meantime I will provide my thoughts on this. I
> personally don't like the use of CSON and CSOFF declarations and prefer to
> fix the code where the number of reported issues is not too high or remove
> the rule from the checkstyle configuration with a TODO comment to revisit
> it later for those rules where the number of breakages is too high to
> consider manually changing the code right now.


I view this as a compromise in the case of absence of unanimous consent.
For example, I don't personally agree with a couple of rules proposed by
Vincent. However, in the interest of resolving the matter, I agreed to
include those rules provided I could override  them in files I author.
However, in general, I agree that it would be best not to include rules for
which unanimous agreement doesn't hold.

In any case, I view style checking as a way to improve code consistency
while recognizing that perfect consistency is antithetical to the human
condition, particularly in an open source project where a central authority
does not dictate behavior.

We are discussing the gray areas here, which are always hard to resolve to
the satisfaction of all. I would prefer to not spend too much time on this,
since there are many more important tasks we face, e.g., driving our bug
list to zero entries, improving test coverage, improving standards
compliance. Bikeshedding on style usage is not a good use of our energy.

If we had only one style rule we agreed on and enforced that rule, it would
be better than none. At present, we have ~50 rules, with perhaps only half
a dozen of these not having full agreement. By my measure, that's a pretty
good situation, even with allowing the exclusion mechanism for these half
dozen or so rules.


>
>
>> For moving forward, i.e., adding new files, we should endeavor to follow
>> the rules when acceptable. However, as a reminder, the goal of using
>> checkstyle is to improve coding consistency when there is general
>> agreement
>> to use some convention. Nevertheless, there remain some style rules for
>> which there is not general agreement. In those cases, I would expect the
>> default (currently specified) rule to apply unless a particular developer
>> wishes to diverge from the default, in which case I have no problem with
>> using CSOFF/CSOK declarations as desired. Personally, I do not agree with
>> a
>> number of the whitespace related (and other) style conventions that are
>> presently encoded in the default rules; as a consequence, I will likely
>> make use of CSOFF declarations in files that I author in order to disable
>> certain rules.
>>
>> I view this use of checkstyle and style rule enforcement as a recommended,
>> but optional process that we developers agree to follow when we can do so
>> and when we agree. I am opposed to any view that would consider these
>> rules
>> to be mandatory or absolute. We represent a community of diverse
>> interests,
>> experiences, and preferences. Imposing a single set of rules in an
>> absolute
>> manner would, IMO, be detrimental to creating a healthy, dynamic community
>> whose opinions do not always coincide. That being said, I think we should
>> also respect the styles used by specific authors; i.e., for cases where
>> there is not unanimous consent to use a specific style rule, we should not
>> change the styles used in a specific file simply because we don't like it.
>>
>
> I agree that it is difficult to reach consensus in a diverse community.
> The rules that go into the final checkstyle file should be only those style
> aspects which have been agreed upon at the time. I know from previous
> discussions that whilst we disagreed on some topics we did reach agreement
> on others. Those which have been agreed should go into the the checkstyle
> file, whilst those which we did not reach consensus on should be removed.
>
>
>
>> For my part, I will henceforth run checkstyle and fix any reported
>> warnings
>> before committing to XGC. I hope that other developers will do this as
>> well.
>>
>
> I agree that once everyone has signed up to the agreed set of checkstyle
> rules that everyone should adhere to this policy.
>
> Thanks,
>
> Chris
>
>  Regards, Glenn
>>
>>
>
> ------------------------------**------------------------------**---------
> To unsubscribe, e-mail: general-unsubscribe@**xmlgraphics.apache.org<ge...@xmlgraphics.apache.org>
> For additional commands, e-mail: general-help@xmlgraphics.**apache.org<ge...@xmlgraphics.apache.org>
>
>

Re: checkstyle-5.5 online for xgc

[Chris Bowditch <bo...@hotmail.com>]

On 03/06/2012 16:58, Glenn Adams wrote:

Hi Glenn,

> I've completed updating XGC to use the same checkstyle-5.5 configuration
> that is currently being used with FOP (trunk). Because a number of XGC
> files do not follow these style conventions, and would produce hundreds of
> warnings were they to be imposed, I have in these cases selectively
> disabled specific rules by inserting CSOFF declarations into the files. I
> believe that is a better approach than making wide scale code changes to
> significantly alter the originally authored conventions.

FYI: Vincent is on holiday this week. I expect he will have some 
feedback on this topic. In the meantime I will provide my thoughts on 
this. I personally don't like the use of CSON and CSOFF declarations and 
prefer to fix the code where the number of reported issues is not too 
high or remove the rule from the checkstyle configuration with a TODO 
comment to revisit it later for those rules where the number of 
breakages is too high to consider manually changing the code right now.

>
> For moving forward, i.e., adding new files, we should endeavor to follow
> the rules when acceptable. However, as a reminder, the goal of using
> checkstyle is to improve coding consistency when there is general agreement
> to use some convention. Nevertheless, there remain some style rules for
> which there is not general agreement. In those cases, I would expect the
> default (currently specified) rule to apply unless a particular developer
> wishes to diverge from the default, in which case I have no problem with
> using CSOFF/CSOK declarations as desired. Personally, I do not agree with a
> number of the whitespace related (and other) style conventions that are
> presently encoded in the default rules; as a consequence, I will likely
> make use of CSOFF declarations in files that I author in order to disable
> certain rules.
>
> I view this use of checkstyle and style rule enforcement as a recommended,
> but optional process that we developers agree to follow when we can do so
> and when we agree. I am opposed to any view that would consider these rules
> to be mandatory or absolute. We represent a community of diverse interests,
> experiences, and preferences. Imposing a single set of rules in an absolute
> manner would, IMO, be detrimental to creating a healthy, dynamic community
> whose opinions do not always coincide. That being said, I think we should
> also respect the styles used by specific authors; i.e., for cases where
> there is not unanimous consent to use a specific style rule, we should not
> change the styles used in a specific file simply because we don't like it.

I agree that it is difficult to reach consensus in a diverse community. 
The rules that go into the final checkstyle file should be only those 
style aspects which have been agreed upon at the time. I know from 
previous discussions that whilst we disagreed on some topics we did 
reach agreement on others. Those which have been agreed should go into 
the the checkstyle file, whilst those which we did not reach consensus 
on should be removed.

>
> For my part, I will henceforth run checkstyle and fix any reported warnings
> before committing to XGC. I hope that other developers will do this as well.

I agree that once everyone has signed up to the agreed set of checkstyle 
rules that everyone should adhere to this policy.

Thanks,

Chris

> Regards, Glenn
>


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: general-help@xmlgraphics.apache.org