On Dec 22, Bryce McKinlay wrote:
> One issue I'd like to raise is that of coding style. A nice feature of libgcj is
> that the code is written fairly consistently, where as classpath varies widely
> between classes and packages that were written by different authors. Although
> there is no official GNU coding standard for Java, libgcj is written according
> to what we think such a standard would look like if it existed.
There was a discussion on this list about coding style, some time ago.
We decided to use GNU coding style (before both GNU and SUN coding
style were allowed), but unfortunately many classes were already
written with a different coding style at that time.
> Should classpath's (and libgcj's?) code should be reformatted to adhere to a
> common style? This could, of course, be easily done using code-formatting tools,
> and in most cases the changes would be relatively minor. I do think that it
> would be a significant advantage to achieve some level of consistency before any
> serious merging work begins. What are the opinions of the classpath developers
> on this?
If there is a code-formatting tool I don't see a reason why we
shouldn't convert. We should make sure that nobody has pending
changes to that class before converting them, though.
Another thing to consider are the copyright notices at the beginning
of the file. We should probably make a template of how they should
look now and use that for all files. Currently classpath has several
different styles of copyright headers.
> Also, I notice that many parts of classpath are documented with javadoc-style
> comments while other parts (and libgcj) leave them out or just have minimal
> comments. The Java APIs are already extensively documented from a variety of
> sources, so it can be argued that such API documentation is redundant.
> Personally I think that large comments make the code a bit harder to read and
> maintain, but I guess that modern editors can be configured to hide javadoc
> comments so that perhaps isn't a real issue. It is also good to have a free (as
> in speech) documentation set. Anyway, this is another style difference between
> the libgcj and some of the classpath code.
I don't think that the comments make the code more difficult to read!
The only case comments might disturb you, is for simple methods, where
the implementation consists of a single line. But if you want to get
a overview of the whole class, its much nicer to look at the javadoc
generated documentation, than to look at the code.
AFAIK, Classpath wants to generate its own documentation. The
comments are also useful to document special things (e.g, that the
Vector.copyInto() can throw an ArrayIndexOutOfBoundsException, even if
that isn't made explicit in the code). It's of course a lot of work
to write comments, and so they sometimes were omitted.
Jochen
