[jsword-devel] coding conventions

[DM Smith]

On 11/04/2009 04:51 PM, Joe Walker wrote:
>
>
> On Tue, Oct 27, 2009 at 7:47 PM, DM Smith <dmsmith at crosswire.org 
> <mailto:dmsmith at crosswire.org>> wrote:
>
>     On 10/27/2009 02:10 PM, Manfred Bergmann wrote:
>>
>>         ----- Original Message -----
>>         *From:* Joe Walker <mailto:joe at eireneh.com>
>>         *To:* J-Sword Developers Mailing List
>>         <mailto:jsword-devel at crosswire.org>
>>         *Sent:* Tuesday, October 27, 2009 5:44 PM
>>         *Subject:* Re: [jsword-devel] coding conventions
>>
>>
>>         On Tue, Oct 27, 2009 at 1:09 PM, DM Smith
>>         <dmsmith at crosswire.org <mailto:dmsmith at crosswire.org>> wrote:
>>
>>
>>             On Oct 27, 2009, at 8:32 AM, Manfred Bergmann wrote:
>>
>>                 Hi have a question about conventions.
>>
>>                 Java coding guideline is to have the brackets not in
>>                 a new line.
>>                 I've seen both in JSword but is it to have new line?
>>
>>
>>             The JSword guideline is to have every { and } on a new
>>             line. This pre-existed my involvement.
>>
>>
>>         It's my fault.
>>         My original thought was that { and } on new lines was more
>>         readable and that the more compact version only made sense
>>         when we were restricted to 80x24. I'm now of the opinion that
>>         the above might be true, however uniformity is more
>>         important, so I'd now do that the more standard way.
>>         I also found the { } in new lines better readable in the past.
>>         Now however my sight about this has changed. Brackets in new
>>         line pull too much the attention and distract too much from
>>         the code which actually is the more inportant thing.
>>
>     I'm up for a change on this one. We just need to settle on a good
>     convention. (Input wanted!)
>
>     I've never been a fan of { being on it's own line, except when it
>     enhanced readability, as in:
>     if (a &&
>          b) {
>          c;
>     }
>     Where a && b is really any compound condition spanning several
>     lines and c appears to line up with the list of conditions. In
>     this case I want to have something to set c apart from the conditions.
>     This could either be the double indentation of the continuing
>     conditions:
>     if (a &&
>             b) {
>         c;
>     }
>     Or of { being on the next line:
>     if (a &&
>          b)
>     {
>          c;
>     }
>     I think the extra indent makes a bit more sense and is easier to
>     enforce with checkstyle.
>
>     Also, I think that for the sake of maintenance and adding new
>     expressions (e.g. debugging) that all single expressions are in a
>     block. That is, not:
>     if (condition)
>        expression;
>
>     and that there are no one liners:
>     if (condition) { expression; }
>
>     I also prefer:
>         } else {
>     over:
>         }
>         else {
>
>     Regarding methods, it gets pretty long to have:
>     scope returnType methodName(parameterList) exceptionList {
>         code;
>     }
>     I think this and class declarations are two places where { should
>     be on the next line. But I could be persuaded otherwise.
>
>     If we change, I'd like to do it one package at a time and have
>     consistency within a package. The Eclipse formatter will make easy
>     work of it.
>
>     Input?
>
>
>  I agree with all your suggestions, with a few of comments:
>
> Are you sure that the output from the Eclipse formatter is what you 
> want. I've generally steered clear of it because there seemed to be 
> many cases where it didn't do what I wanted. If it does, then 
> excellent, perhaps the formatter settings should be exported into the 
> project somewhere.
In the past I steered clear of it too. I really do not like how it 
handled long lines. And I don't like how it handles arrays. While I 
don't care much for how it formats JavaDoc, it was certainly more readable.

What I did was to format each file with it, one at a time and Eclipse 
was good enough to indicate what lines it changed in the left near the 
line numbers. Right clicking on the change indicator give choices to 
revert the line or the block. I then reviewed each file, reverting what 
was unfortunate.


> Many people have monitors that can either swivel, or be sideways 
> mounted. I personally greatly prefer to see more lines of code this 
> way. However the downside is to restrict the horizontal size, so I 
> generally stick to 80 columns now, and I know that companies like 
> Google have hard line length limits in their style guidelines for 
> exactly this reason. However if this doesn't fit with your style, 
> please ignore.

I, too, don't like to horizontally scroll. I hadn't thought about 
swiveling the monitor and with my current one, I can't.

I think 80 or so makes sense as it is much more readable than 160 (which 
is what I used when reformatting). The places where the lines are longer 
than 80 were mostly due to indentation and/or should have been split up 
into multiple statements. I find that deep indentation makes for code 
that is hard to understand.

I need to fix up the checkstyle report to not report on the { brace 
placements. Maybe I'll have it report on long lines and clean those up.

Thanks Joe for your input.

In Him,
     DM
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.crosswire.org/pipermail/jsword-devel/attachments/20091104/020343ff/attachment.html>