[kepler-dev] Kepler coding style

[Christopher Brooks]

Hi Chad,
My comments are below.  I think we can probably arrive at a reasonable
solution that accomodates all views.

> Christopher wrote:
>> 11) Now might be a good time to fix up the indentation of the files
>> by running a tool like the Eclipse indenter.  The files are pretty hard
>> to read.  modules/util/src/org/kepler/gui/TabbedLibraryPane.java is an
>> example.

Aaron wrote:
 > I just wanted to super second this motion.  I've been biting my lip
 > ever since I got here to not just reformat the entire codebase and do 
 > one massive checkin...  We also need to clean the imports, this is
 > something I ran into when dealing with bundle dependencies, which 
rely > on having accurate import statements.

Chad wrote:
> My style or yours :)   I think we've had this discussion a few times.
 > while I'm all for having a uniformly styled code base, I also hate
 > working with other peoples' styles.  I know that I learned in CS101
 > that I need to just deal with it or talk to a psychologist about it
 > or something, but I still feel like it hampers my productivity when
> I have to use a style that doesn't jive with the way I write code.
 > The rule that we've had for a long time is that the file should be
 > styled in the author's format and that it should stay that way.  If
 > There is a file that is not formatted at all, or does not follow any
 > style guidelines (i.e. lines of the same block are not indented to the
> same tab point, etc) then I have no problem reformatting them. 

I think there are various degrees of formatting.  I'd be happy with
just fixing the indenting.  I don't have time to individually fix up
formatting in Kepler files.  Partly it is because I prefer to work
strategically at the project level as opposed to working on individual
files.  Partly it is the way I work - when I'm coding, I'm working
on a few files - when I'm cleaning code, I want to focus on cleaning
the code in lots of files and not changing the functionality at the
same time.

The Eclipse formatter does a reasonable job of formatting files.
The Ptolemy Project uses the Java Style instead of the Eclipse style.
One thing we do is disable comment level formatting, which is something
you would appreciate.  The steps we take are at:
http://chess.eecs.berkeley.edu/ptexternal/nightly/doc/coding/eclipse.htm

 > Under the "Indentation" tab, change the Tab policy to "Spaces only".
 > Under the "New Lines" tab, select "at end of file"
 > Under the "Comments" tab, unselect "Enable block comment formatting"

So, how about we run the Eclipse formatter using the Java style and
not format the comments?  This would likely change other things,
so we could fall back to just trying to indent the code.

Off the top of my head, I see the following formatting changes in
rough order of intrusiveness, from least intrusive to most intrusive.

- Add a trailing newline (necessary if we are to run Unix scripts)
- Convert tabs to spaces (some people use 4 spaces per tab, some 8 spaces)
- Remove trailing whitespace (makes files smaller)
- Fix imports
- Fix indenting

I think you can probably live with the changes above.
You might want to use a particular indentation style though.

Other changes:
- Uniform policy for curly brackets
- Various other layout issues
- Ordering methods - note that this can change semantics

Eclipse also has a code cleanup option that does more aggressive
things to the code.  I run this on the Ptolemy code so that
the code is more uniform.

I'd also like to see doccheck run and the warnings fixed,
see 
http://chess.eecs.berkeley.edu/ptexternal/kepler/docCheck/PackageSummary.html
Findbugs warnings should also be addressed.
http://chess.eecs.berkeley.edu/ptexternal/kepler/kepler-findbugs.htm

I think that Kepler should have a uniform style, and I really don't
care what it is as long as it is uniform.  I can code in pretty much
any style, especially if I know that a tool will come along and fix
up any small mistakes I make in indenting.  So, if you want to define
a style in a formatting tool that works for you, then go for it.

The bottom line about style is that someone needs to determine the style
and then a tool should enforce the style.  I don't think the
current policy of having people fix the style on individual files
is working, the files I looked at were pretty rough and need an
automated cleanup.

I'm even fine with variation in the style between different modules,
especially if the style is well defined, uniform within the module
and enforced by a tool.

Comments?  Can we find a common ground on an automated tool that
is run on all the code?

_Christopher


-- 
Christopher Brooks (cxh at eecs berkeley edu) University of California
CHESS Executive Director                      US Mail: 337 Cory Hall
Programmer/Analyst CHESS/Ptolemy/Trust        Berkeley, CA 94720-1774
ph: 510.643.9841 fax:510.642.2718	      (Office: 545Q Cory)
home: (F-Tu) 707.665.0131 (W-F) 510.655.5480