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
