Jochen Hoenicke wrote:
> 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.
Great - I will experiment with the various code formatting tools and report back what
I come up with. There is currently no document describing the libgcj coding style,
but I think it would be good to have one. If I get time I'll see if I cant put
something together. I'm going to be away from my development machine for the next
week or two, 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.
Personally those huge page-long GPL copyright headers also bug me a bit. Its a safety
issue, they put stress on my mouse-wheel finger ;-). It would be great if we could
just stick to something like:
/* Copyright (C) 1999, 2000 Free Software Foundation, Inc.
This file is part of Classpath.
This software is copyrighted work licensed under the terms of the
Classpath License. Please consult the file "CLASSPATH_LICENSE" for
details. */
(this is modelled on the Cygnus libgcj header).
> 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.
Thats true, but from my perspective when I'm looking at source code I usually want to
know HOW something is implemented, or to establish why I'm seeing a particular
erronous behaviour. Its easier and quicker to get a nice overview of how a class is
implemented by not having to wade through a few screens of javadoc that is only a
reproduction of what I already have open in Netscape in a different window, or in a
java book in front of me. Javadoc comments also draw my attention away from the
*important* comments - those which document particular implementation details, known
problems, etc.
> 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.
Yes - while I *do* see the value in having such documentation (so it can be
distributed wherever classpath is distributed without requiring end users to obtain
the API documentation from elsewhere), I for one would rather spend my time writing
quality code than rehashing API documentation which already exists in five zillion
java books and endless free-as-in-beer html documentation. There is also a copyright
issue here - how can we write clean-room javadoc comments when the origional javadoc
was what we based out implentation on in the first place??
regards
[ bryce ]
