[ Resending this because it got lost last time? ]
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.
> 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
original javadoc was what we based out implentation on in the first
place??
regards
[ bryce ]
