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. 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, and since it is widely used, including either a recommendation to use a particular format set or a Jena-provided set. 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." 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? And when you write, "Use @formatter” do you mean to use the Eclipse formatter or to use it in a particular way? 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? I can start a simple page with this stuff, if that is helpful. --- A. Soroka The University of Virginia Library > On Nov 25, 2015, at 5:54 AM, Andy Seaborne <[email protected]> wrote: > > How about a "guide for contributors" on the cwiki? Nothing too heavy, > > Quick outline: > > 1. Code > 1.1. Preferred, not mandatory, formatting. > 1.2. About warnings. > 1.3. Use @formatter: (i.e. the default because it is configurable) > 1.4. Minimise whitespace changes > 1.5. Spaces, not tabs > > 2. About commits, rebase and squashing > It's about the contribution, and the ASF record, not the minutiae > of how it got there. > > 3. About the IP - be clear that contributor is making a contribution. > > 4. Please open a JIRA > > 5. Process : What next? > > > > Inspired by Rob, I have also been reformatting code (usually when I was > involved in it in the first place) as and when time is right. Eclipse > reformatting is not perfect and there are a few places Eclipse makes a mess > of it (comments) and places where it simply can't know (good places to break > long lists). Currently, it does not always make a good job of lambdas > either, not that old code has many; I'm sure this will improve in Eclipse > releases. > > I find I need to reformat files in pieces, between significant comment blocks > and the process is not automatic. > > The other thing that reformatting does is make diff'ing old versions useless. > (The repacking chhj to oaj made that messy but it is still possible.) > > So I'm not in favour of retro-formatting. > > 1) : yes > 2) : I use one liners if appropriate, general only for getters/settings, not > elsewhere. > > Andy > > On 24/11/15 09:41, Rob Vesse wrote: >> Yes to (1) and No to (2) >> >> (2) is only readable for trivial definitions IMO >> >> Personally I've been applying an Eclipse format to all new Jena code I >> write and any existing code I substantially rewrite as I go over the past >> few years. >> >> Broadly speaking it does the following: >> >> - Spaces instead of Tabs with 4 spaces indentation >> - Brace style per (1) >> - Max code line width of 120 (max comment line width 80) >> - Some specific indentation options to make Javadoc readable inline >> - Enables //@formatter:off and //@formatter:on directives for fencing code >> blocks you want to keep formatted in a particular way, I tend to use this >> for test data that would otherwise be rendered unreadable by reformatting > > > >> If we really want to standardize on a format then we should use an Eclipse >> format (or other IDE equivalent) so that everybody can automatically apply >> the chosen style and have a policy of cleaning up as we go. >> >> I'd be against going through and reformatting everything en-masse just for >> the sake of it >> >> Even if we do reformat as we go we would ideally commit the reformats >> separately from whatever other changes we make so that the specific >> changes can be reviewed in isolation from the reformats (though this is >> something of a judgement call depending on how much code is in the file >> being reformatted) >> >> Rob >> >> On 23/11/2015 18:05, "A. Soroka" <[email protected]> wrote: >> >>> A while ago, I broached the topic of code standards, and there was a >>> certain amount of agreement on a few general points, none of which were >>> terribly controversial. >>> >>> I want to open a similar topic: code formatting. There are a variety of >>> different forms of code layout in Jena, which is not surprising for a >>> project of long running and much participation. I’d like to suggest that >>> Jena normalize its codebase in two very simple and pretty boring ways. >>> These are just suggestions, of course. If there is agreement on one or >>> both of them, I would be happy to do the work to format the current >>> codebase to match, which, being entirely non-functional, shouldn’t >>> require much review. >>> >>> 1) Braces and control statements and declarations: 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, so: >>> >>> public void foo() { >>> // do stuff >>> } >>> >>> instead of: >>> >>> public void foo() >>> { >>> // do stuff >>> } >>> >>> 2) Single-statement or empty declarations on one line, so: >>> >>> protected Foo() { this(false) ; } >>> >>> and not: >>> >>> protected Foo() { >>> this(false) ; >>> } >>> >>> I think introducing that little bit of uniformity would make the code a >>> little easier to scan and read at almost no cost. Thoughts? >>> Diasgreements? Rotten tomatoes? {grin} >>> >>> --- >>> A. Soroka >>> The University of Virginia Library >>> >> >> >> >> >
