incubator-jspwiki-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Janne Jalkanen <Janne.Jalka...@ecyrd.com>
Subject Re: Switching to different bracing style?
Date Sat, 20 Jul 2013 14:50:44 GMT

I am not sure whether you want anyone on the team who would be unable to adapt to the existing
coding style.

It is a drastic change and typically only reserved for major releases.  Otherwise you risk
a fork, or pissing off seriously a number of people who cannot contribute to the existing
codebase (e.g because they are running an internal version of JSPWiki with their own custom
patches).  That's all I am saying.

/Janne

On Jul 20, 2013, at 17:35 , Glen Mazza <glen.mazza@gmail.com> wrote:

> Hi Janne, we're making 100's of other changes to the source code as part of the Sonar
fixing, so, yes, rebasing will continue to be a necessity for anyone who wishes to fork off
trunk instead of a release.  We can't keep the code (formatting and libraries) obsolete out
of fear that someone forking off trunk might have to update their own code as a result--that
goes with the territory of coding off trunk instead of a specific release.
> 
> Further, these changes (along with the library modifications) are designed to encourage
more committers on to the team, by using a coding style that they're accustomed to and comfortable
with on their other open source projects.  Those people who might need to rebase will still
be ahead due to all the extra committers and work that working in a modern environment would
presumably bring in.
> 
> Backwards compatibility shouldn't be an issue, as this is just a formatting matter. 
Likewise, I'm distinctly trying to avoid the "poison pill" of saying that the changes must
all be done at once or not at all, given that nobody would have the time to do it all at once,
that would be akin to saying that it would never get done at all (although Ichiro is mentioning
IDEs might be able to automate this for us.)  This is just for moving forward, and if necessary
I would even accept those accustomed to Style B continuing with it, I just expect them to
be overwhelmed by the Style Cers.  And replacing the Style A with Style B--the reason why
I first posted this issue--just looks *awful*.
> 
> (BTW, Janne, since you're still here, https://issues.apache.org/jira/browse/JSPWIKI-778
has *your* name written alllll over it.  :)
> 
> Glen
> 
> 
> On 07/20/2013 07:28 AM, Janne Jalkanen wrote:
>> BTW, changing the coding convention also means that anyone maintaining any sort of
a patch against the current codebase will  need to do a complete rebase.  Which is why I would
advise against doing anything so drastic except during major releases (which can be expected
to break backwards compatibility anyway).
>> 
>> /Janne
>> 
>> On Jul 20, 2013, at 13:32 , Ichiro Furusato <ichiro.furusato@gmail.com> wrote:
>> 
>>> Hi Janne,
>>> 
>>> I've looked around the Apache site and unfortunately can find no ASF-wide
>>> coding conventions. It seems that ASF has never had a consistent set of
>>> conventions across its many projects, with some choosing an Avalon-like
>>> style for braces to avoid the K&R style (with all other syntax following
>>> the Sun standard). Other projects adopted other styles. There are many to
>>> choose from: Ambler, Lea, ESA (yes, the European Space Agency). Given no
>>> one "standard" is without flaws in someone's eyes this is not entirely
>>> surprising. While I don't like every bit of it, the one benefit of the Sun
>>> standard is that it is by far the most widely known and practiced, if we
>>> aren't too strict in interpretation.
>>> 
>>> I do note one thing clearly expressed on the JSPWikiCodingStandard page: no
>>> one seemed remotely in agreement about what constitutes "increased
>>> readability". It seems what one person thought readable others thought not
>>> so readable.
>>> 
>>> A point you made was that once anyone had checked code into the JSPWiki
>>> project it was no longer the domain of the original programmer but became
>>> "common code". By the same token, code checked into the Apache JSPWiki
>>> project is now the domain of the ASF. Since historically it seems that each
>>> ASF team has chosen its own coding conventions, developers should therefore
>>> follow whatever conventions are chosen for the project by the project team,
>>> which I guess is the question before us.
>>> 
>>> That is, unless someone from ASF has some guidance.
>>> 
>>> Ichiro
>>> 
>>> On Sat, Jul 20, 2013 at 6:47 PM, Janne Jalkanen <Janne.Jalkanen@ecyrd.com>wrote:
>>> 
>>>> Reasoning for style "B", aka K&R is here:
>>>> http://ecyrd.com/JSPWiki/wiki/JSPWikiCodingStandard
>>>> 
>>>> I do believe Sun made a mistake going for not aligning the braces - my
>>>> experience is that keeping braces on the same line significantly increases
>>>> code readability and works better in multi-line conditionals.
>>>> 
>>>> /Janne
>>>> 
>>>> On Jul 20, 2013, at 06:26 , Ichiro Furusato <ichiro.furusato@gmail.com>
>>>> wrote:
>>>> 
>>>>> Hi,
>>>>> 
>>>>> I'd much prefer Style C as that's the "Sun standard", as you note used
in
>>>>> many Apache projects, and the default style of Eclipse's Format command,
>>>>> which means that it's easy to auto-format an existing file to match the
>>>> Sun
>>>>> standard. Style B is IMO a bit ridiculous -- it extends the logic of
a
>>>>> class vertically across so many lines that it becomes actually hard to
>>>> read
>>>>> and the only benefit seems to be increasing the count of lines for those
>>>>> who think that's a benefit. But rather than be ambiguous about it, I'd
>>>>> suggest we simply reference the actual style of "Style B" in JSPWiki's
>>>>> documentation:
>>>>> 
>>>>>   Code Conventions for the Java Programming Language
>>>>>   http://www.oracle.com/technetwork/java/codeconv-138413.html (home
>>>> page)
>>>>> 
>>>> http://www.oracle.com/technetwork/java/javase/documentation/codeconvtoc-136057.html(web
>>>>> TOC)
>>>>>   http://www.oracle.com/technetwork/java/codeconventions-150003.pdf(PDF)
>>>>> 
>>>>> I'm not sure where Style B came from in the JSPWiki project, as the Sun
>>>>> standard has been around for a very long time.
>>>>> 
>>>>> FWIW, all of the code for the Neocortext project (which uses JSPWiki
as a
>>>>> component) is roughly in the Sun standard (without being anal about it),
>>>>> and I'd much prefer to not have to reformat the code for Style B in order
>>>>> to submit any portions of it, such as plugins, etc.
>>>>> 
>>>>> So while I don't have a vote, +1 for Style C.
>>>>> 
>>>>> Ichiro
>>>>> 
>>>>> 
>>>>> 
>>>>> On Sat, Jul 20, 2013 at 9:35 AM, Glen Mazza <glen.mazza@gmail.com>
>>>> wrote:
>>>>>> Hi Team, the next Sonar complaint, and there's a significant 500
of them
>>>>>> within JSPWiki, is that we're not using braces for single-line
>>>> if/while/for
>>>>>> loops.  I know for CXF braces are always required, and I suspect
the
>>>>>> majority of Apache projects today also disallow them, so the
>>>> requirement is
>>>>>> not unreasonable.  Fixing them is not the problem, what *is* the
>>>> problem is
>>>>>> our older-fashioned bracing system, i.e., instead of switching from
this
>>>>>> 
>>>>>> Style A:
>>>>>> 
>>>>>> if (a > b)
>>>>>>  c = 10;
>>>>>> else if (d > e)
>>>>>>  f = 20;
>>>>>> 
>>>>>> to this (the bracing system JSPWiki presently uses):
>>>>>> 
>>>>>> Style B:
>>>>>> 
>>>>>> if (a > b)
>>>>>> {
>>>>>>  c = 10;
>>>>>> }
>>>>>> else if (d > e)
>>>>>> {
>>>>>>  f = 20;
>>>>>> }
>>>>>> 
>>>>>> I'd like to be doing this instead:
>>>>>> 
>>>>>> Style C:
>>>>>> 
>>>>>> if (a > b) {
>>>>>>  c = 10;
>>>>>> } else if (d > e) {
>>>>>>  f = 20;
>>>>>> }
>>>>>> 
>>>>>> I've checked five major open source projects -- Style C is all they
use:
>>>>>> 
>>>>>> CXF - http://svn.apache.org/viewvc/**cxf/trunk/rt/transports/http/**
>>>>>> src/main/java/org/apache/cxf/**transport/https/**
>>>>>> CertConstraintsFeature.java?**revision=828758&view=markup<
>>>> http://svn.apache.org/viewvc/cxf/trunk/rt/transports/http/src/main/java/org/apache/cxf/transport/https/CertConstraintsFeature.java?revision=828758&view=markup
>>>>>> Camel - http://svn.apache.org/viewvc/**camel/trunk/components/camel-**
>>>>>> atom/src/main/java/org/apache/**camel/component/atom/**
>>>>>> AtomUtils.java?revision=**1190212&view=markup<
>>>> http://svn.apache.org/viewvc/camel/trunk/components/camel-atom/src/main/java/org/apache/camel/component/atom/AtomUtils.java?revision=1190212&view=markup
>>>>>> Tomcat - http://svn.apache.org/viewvc/**tomcat/trunk/java/org/apache/**
>>>>>> catalina/filters/FilterBase.**java?revision=1189413&view=**markup<
>>>> http://svn.apache.org/viewvc/tomcat/trunk/java/org/apache/catalina/filters/FilterBase.java?revision=1189413&view=markup
>>>>>> Hadoop - http://svn.apache.org/viewvc/**hadoop/common/trunk/hadoop-**
>>>>>> mapreduce-project/hadoop-**mapreduce-client/hadoop-**
>>>>>> mapreduce-client-common/src/**main/java/org/apache/hadoop/**mapred/**
>>>>>> LocalDistributedCacheManager.**java?revision=1466196&view=**markup<
>>>> http://svn.apache.org/viewvc/hadoop/common/trunk/hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-common/src/main/java/org/apache/hadoop/mapred/LocalDistributedCacheManager.java?revision=1466196&view=markup
>>>>>> Spring Framework: https://github.com/**SpringSource/spring-framework/**
>>>>>> blob/master/spring-jdbc/src/**main/java/org/springframework/**
>>>>>> jdbc/object/SqlFunction.java<
>>>> https://github.com/SpringSource/spring-framework/blob/master/spring-jdbc/src/main/java/org/springframework/jdbc/object/SqlFunction.java
>>>>>> Style B might be OK for projects that still allow Style A, but it
makes
>>>>>> the code too bloated once Style A is disallowed.  I don't think we'll
be
>>>>>> able to attract many committers sticking with Style B anymore.
>>>> Basically,
>>>>>> to avoid the busywork of converting Style B to Style C, we'll allow
>>>> either
>>>>>> in our source code but with the expectation that more and more code
>>>> will be
>>>>>> adopting Style C as time moves on, how does that sound?  (Or, do
we
>>>> want to
>>>>>> continue with allowing Style A and Style B?--we're welcome to ignore
>>>> Sonar
>>>>>> on this.)
>>>>>> 
>>>>>> Regards,
>>>>>> Glen
>>>>>> 
>>>>>> 
>>>> 


Mime
View raw message