I’m no longer sure this conversation is a good one to continue right now, or
that it’s a good idea for me to try to produce any documentation therefrom. It
doesn’t seem like there is consensus on anything except “Code should be clear
to whomever is examining it, whatever that means for that person.” Conversation
on a recent PR between Osma Suominen, Andy, and myself demonstrated the
unsurprising fact that what is clear to one person often isn’t clear to someone
else, so this doesn’t seem like a good principle on which to build any policy.
{grin}
If there are concrete changes to be made (like generating Eclipse formatters or
writing guides for an agreed-upon style) I’d be happy to help with those.
---
A. Soroka
The University of Virginia Library
> On Nov 25, 2015, at 10:21 AM, Andy Seaborne <[email protected]> wrote:
>
> This does not reflect what I though I said earlier.
>
> On 25/11/15 11:26, A. Soroka wrote:
>> Okay, sounds like (so far) in the realm of pure code format
>> questions, there is some support for:
>>
>> Braces to be used with control statements only where required, and
>> when used with either control statements or declarations, to open on
>> the same line.
>
> And when needed for clarity.
>
> if () {
> large, long single
> statement
> over many lines
> benefits from {}
> }
>
> and with streams, this is more likely.
>
> I'd like to see more emphasis on clarity, less on rules.
>
>>
>> No to retroactive reformatting, but yes to piecemeal reformatting as
>> it becomes convenient in the process of other PRs.
>>
>> No mandatory stuff (e.g. no Checkstyles rules that fail the build).
>>
>> Positive support for Eclipse formatting
>
> "Some support"
>
>> ,and since it is widely used,
>> including either a recommendation to use a particular format set or a
>> Jena-provided set.
>
> Depends on the weight of "recommend".
>
>> Recommending or providing a set for Eclipse is
>> probably enough (IntelliJ and NetBeans can use Eclipse formats). Are
>> there objections to the Eclipse default settings? I just checked, and
>> they do support the braces-or-no formatting above, so that
>> recommendation could be subsumed into just “Use the Eclipse default
>> settings to format."
>
> The default Eclipse settings (the ones "Eclipse [built-in]") are tabs.
>
> -1
>
> contradicts
>
>>> 1.5. Spaces, not tabs
>
> and I'm not the only one.
>
> Most of the code base is spaces, not tabs.
>
> You, and Claude, chose to use tabs.
>
> Eclipse default is tabs, tab=4, then display on GitHub, where the default is
> tab=8, is bad, especially for split lines.
>
>> Andy, when you write “About warnings.” do you mean to have some
>> documentation available about which warnings are and are not
>> acceptable, or something else?
>
> We are not going to get much agreement on warnings settings judging by the
> situation so far.
>
>> And when you write, "Use @formatter”
>> do you mean to use the Eclipse formatter or to use it in a particular
>> way?
>
> @formatter:off / @formatter:on is the Eclipse control to stop the formatter
> on sections of a file that should not be touched.
>
>> I’ve got nothing to say about the other things Andy outlines below.
>> They all seem very straightforward to me, except one very minor
>> point: Andy, it might be good in 2 to explicitly say that while it’s
>> not necessary for people to squash or rebase PRs themselves,
>> committers might do various things like that before merging. I know
>> that should go without saying, but sometimes it’s nice to be
>> explicit.
>>
>> Is there any support for a (un-fail-able) Checkstyles step in the
>> build, to give feedback on code formatting across the modules?
>
> Not from me.
> It's about a mandatory, fixed, agreed style.
>
> It's LGPL 2. But at least it has a "no tabs" check.
>
>>
>> I can start a simple page with this stuff, if that is helpful.
>>
>> --- A. Soroka The University of Virginia Library
