Code formatting (Was: [patch] Small fix for java.beans)

[Mark Wielaard]

Hi,

On Fri, 2003-10-24 at 17:22, Arnaud Vandyck wrote:
> > I have to learn so I can reformat this file. I'll send a patch asap ;)
> 
> Attached is the patch and here is the Changelog entry:
> 2003-10-24 Arnaud Vandyck <address@hidden>
> 
>       * gnu/java/beans/IntrospectionIncubator.java: reformated to conform to
>     the GNU standards
> 
> Waiting for your comments, thanks,

Thanks so much for doing this.
I think this is mostly the way we want it, but to be honest we never
really set down all formatting rules that we want to use.

So we are now forced to actually think about it and write down the code
formatting convention we should use. People have been complaining about
the different styles we now have in the source tree and the fact that
there isn't a clear description of the formatting conventions that
should be used. So here we go...

And please comment, but be gentle, since obviously it is mostly a matter
of taste. I tried to give some rationals to make it look less arbitrary,
but I am sure you can come up with your own rationals :) But if we can
agree on something then we can also start making sure that we have the
tools to do the auto-formatting for us!

First the easy one, C files. We should just use the standard GNU Coding
Standards for that. <http://www.gnu.org/prep/standards_23.html>
There are lots of tools that can automatically generate it and it seems
as good a standard as any.

For .java source files I recommend to follow the GNU Coding Standards
for C as closely as possible. With a few exceptions:
(This is almost, except for the method/space thing, how Brian summarized
 it: http://mail.gnu.org/archive/html/classpath/2003-05/msg00025.html)

- Since method definitions don't start in column zero anyway (since they
are always inside a class definition), the rational for easy grepping
for "^method_def" is mostly gone already. Since it is customary for
almost everybody who writes java source code to put modifiers, return
value and method name on the same line, we do to.
[Another rational for always indenting the method definition is that it
makes it a bit easier to distinguish methods in inner and anonymous
classes from code in their enclosing context. NEED EXAMPLE.]

- Don't add a space between a method or constructor call/definition and
the open-bracket. This is because often the return value is an object on
which you want to apply another method or from which you want to access
a field.
        
        Example:
                getToolkit().createWindow(this);
        
        NOT:
                getToolkit ().createWindow (this);

- Look at the examples in the GNU Coding Standard it gives examples for
almost every construct. One missing is the try-catch which should be
formatted as:

  try
    {
      //
    }
  catch (...)
    {
      //
    }

- Don't put multiple class definitions in the same file, except for
inner classes. File names (plus .java) and class names should be the
same.

BTW. One line really is a max of 80 characters (this also goes for
ChangeLog Entries).

[Things not documented yet - need to get some sleep now...]
= Describe standard header, blank line, package statement, blank line,
  imports (sorted, use * when more then 3 from same package), blank
  line.
= Anonymous classes.
= Naming conventions.
= API doc javadoc tags used.
= ChangeLog entry guide
  http://mail.gnu.org/archive/html/classpath/2003-08/msg00066.html
= Examples, examples, examples.

All the above is of course a bit arbitrary, but I hope it is not that
controversial.

Now we need to stick to these guidelines and adapt some source
formatting tools to do these things automatically. And standard settings
for emacs, vim, eclipse...

Cheers,

Mark

signature.asc
Description: This is a digitally signed message part