Re: [java-gnome-hackers] Code formatting

[Andrew C. <an...@op...>]

On Tue, 2005-23-08 at 12:03 +0100, Ismael Juma wrote:
> In addition, I am more in favour of using an established convention
> instead of creating yet another one.

a) I really don't think it matters. What matters is that we, the people
working on the code, use the same style, whatever and whichever it is.

b) That said, I had a good chat with ijuma on IRC a touch earlier. I was
a bit leery because of scepticism about whatever said "established"
convention might be. Well, it turns out that Eclipse (now, anyway) ships
with a few pre-configured styles. One of them is called "Java
default" (whatever that means). I did a diff between what I sent round
and that style, and it came up with only 14 out of 241 items that were
different, How 'bout that. Not bad for having manually configured it to
be "what looked about right". And it's even better - several of those
seemed driven by the wrap issue (see below).

...
>  I also have a few reservations
> about the profile being proposed here,
...

ijuma noted a couple issues to me. Since the number of divergences from
that "default", (wherever the hell it came from) was so few, perhaps we
can chat about them individually after all.

Here they are:


1) word wrap.
------------

the thing I sent round is configured to wrap comments and JavaDoc at 80
wide, but to wrap most everything else at 120 (there are some subtleties
that I fine tuned, but the Eclipse formatter defaults were generally
sensible).

The rational behind that was this:

Comments (be they /* */ or JavaDoc) *really* need to be fully readable
at a glance in a text editor or viewer. And given standard terminal
width of 80, 80 it is.

Code, on the other hand, can be a bit wider. Two things - first, Eclipse
is rather smart about it which is good; second, wrapping code at 80
produces a lot of artifacts like this:

                  throw new IllegalArgumentException(
                      "The message that I need to tell you about at length");


which I found a touch silly. It's worse with strings concatenated
together with + operators.

My sense was that many of us aren't terribly worried by a line going off
the screen. To a point, of course, but a few characters > 80 isn't such
a big deal and helps preserve flow. And given the proliferation of
indenting in nested classes and listener/event pattern instances, you
end up working a fair way across the screen fairly often. No need to
wrap so harshly.

Given larger screens (be they IDEs or editors in maximized terminal
windows) there is generally more width to work with and so 120 seemed to
minimize unnecessary wrapping. There does come a point though, where
really it's time to wrap 'round. Once I found myself with a 400
character wide method call. Ouch.

So like I said, 120 made good sense from a readability perspective, both
on screen an in diffs.



2) Tabs vs spaces for indenting. 
-------------------------------

Religious issue to be sure. Don't suppose it matters much. Tab width of
4 is pretty common in the Java world. 

But some use spaces, and some use tabs with a width setting of 4.
java-gnome is full of both. We should pick one.

As I sent it round, the code style has tabs only which has been my
preference as both Eclipse and vim knew what to do about things. The
Java "default" (whatever) had spaces.

There actually is an argument against tabs which, generally, is "well,
your terminal DOESN'T know about context dynamic TAB widths, so output
to terminal (ie, cat or less or grep) is "different" than in editor"

<shrug> 

I hit the tab key, and in most places I get a TAB. Good enough for me,
but whatever. I'll revert to spaces if that's what is deemed prudent.


3) aligning columns
-------------------

In field declarations, the Java "default" and my style align the
columns. Ismael pointed out that much of java-gnome to date hasn't done
this.

I rather suspect that the simple reason is that no one felt like
bothering. I've been doing in manually since my C days 15 years ago, and
so I do rather find Eclipse doing in automatically rather nice.

So it's a default, but he mentioned it, so I mention it here.

It think it looks great.


4) class declaration brace
--------------------------

I've always been of the habit of not inserting newlines before
{ characters (if/else, functions, etc).

But somewhere along the line I picked up the habit that the one and only
place I do stick in a new line is class declarations. So:

        public class Triangle extends Shape implements Metric
        {
        	int	_var;
        
        	public Triangle() {
        		blah();
        		if (true) {
        			return;
        		} else {
        			throw new Exception();
        		}
        	}
        	
        	...
        }

Instead of 

        public class Triangle extends Shape implements Metric {
        	int	_var;
        
        	public Triangle() {
        		blah();
        		if (true) {
        			return;
        		} else {
        			throw new Exception();
        		}
        	}
        	
        	...
        }


Take your pick. I like the former, as seems to highlight the
significance of a nested inner class declaration quite well.

Whatever. We need to pick one.


And that's about it.
-------------------

> but I will refrain from
> commenting 

One thing Ismael raised was a personal preference on HIS part. Since I
have expressed preference on a few things, no reason that others can't
as well. So here's one:

5) catch block style:
--------------------


 Ismael happens to like try / catch blocks that look like this

        try {
        	blah();
        }
        catch (Exception e) {
        	e.printStacktrace();
        }

Instead of 

        try {
        	blah();
        } catch (Exception e) {
        	e.printStacktrace();
        }

Which is the "default" and happens to be my preference as well.

Oh, he applies his way to else blocks as well. Ewww! :)


> I believe we should do this after the release and just before branching.
> >>>From previous releases, it seems like we usually branch sometime after
> the x.x.1 release.

ijuma made a good argument on why we should waiting until after this
release, to do with the memory management fix set. I'm unconvinced, but
if that makes him and Nick feel better, so be it. I definitely think it
important to do the reformat before branching, though, and am glad
Ismael agrees. An additional reason he raised - to make back-porting and
forward-merging between branches easier.

Since tarballs for 2.12.1 are due 3 Oct 05, I will plan carry out and
commit a reformatting (with whatever style this thread settles on)
sometime that week.

AfC
Sydney