[Jython-dev] Coding standards

[Jeff A. <ja...@fa...>]

Possibly a yawn-worthy topic for some, or a rich source of flame-wars. 
There is a practical issue: when we're creating change-sets, and reading 
them, there will be a lot more change to read if each of our IDEs is 
normalising to a different set of conventions. [1]

We have this page: https://wiki.python.org/jython/CodingStandards on the 
not-much-loved Wiki. Apart from some project-specific preferences, the 
main thing it says is "follow the Sun Java Coding Conventions". The link 
is broken (again) but I found them here: 
http://www.oracle.com/technetwork/java/javase/documentation/codeconvtoc-136057.html

They still look good to me, but are not maintained (why not?).

The other thing we've done is to provide an Eclipse formatting profile 
(thanks to Charlie Groves in 2008). I use Eclipse and I found this 
mostly satisfactory except when it comes to line-wrapping. For method 
calls and declarations, it likes each argument on a new line, in which 
it contradicts the Sun conventions we just recommended. This is also not 
what we find in most of the code base either, so my variant wraps like 
Sun's "indent at 8 spaces". 
(http://www.oracle.com/technetwork/java/javase/documentation/codeconventions-136091.html#248). 
It's mostly line-wrapping issues that have me tweaking the formatter. 
Also, I made choices about features new since 2008 (lambda, 
try-with-resources) where the default seemed inconsistent with other 
formatting.

I have some save actions set in Eclipse, like adding {} to if clauses, 
@Override where recommended, and stripping trailing space (which I find 
it puts in easily), but they don't get saved as part of the formatter.

If no-one objects, I'll post this slightly tweaked formatter. It's not 
much different, honest. I did this once before, but I think we lost it 
in the great defacement.

We should recommend this page to contributors who seem not to be aware 
of it. Can we help them with formatters from other IDEs that enforce 
more-or-less the same standard?

Jeff


[1] For this reason, if I spot that there will be a lot of reformatting 
of some files, I make that reformatting first in a change set of its 
own, so it can be ignored.

-- 
Jeff Allen