[jsword-devel] coding conventions

[Joe Walker]

On Tue, Oct 27, 2009 at 7:47 PM, DM Smith <dmsmith at crosswire.org> wrote:

>  On 10/27/2009 02:10 PM, Manfred Bergmann wrote:
>
>
>
> ----- Original Message -----
>  *From:* Joe Walker <joe at eireneh.com>
> *To:* J-Sword Developers Mailing List <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> 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.

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.

Joe.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.crosswire.org/pipermail/jsword-devel/attachments/20091104/b996768a/attachment.html>