hacking.texinfo

linux下建立JAVA虚拟机的源码KAFFE

@item
Because the output of different compilers differs, we have
standardized on explicitly specifying @code{serialVersionUID} in
@code{Serializable} classes in Classpath.  This field should be
declared as @code{private static final}.  Note that a class may be
@code{Serializable} without being explicitly marked as such, due to
inheritance.  For instance, all subclasses of @code{Throwable} need to
have @code{serialVersionUID} declared.
@c fixme index
@c fixme link to the discussion

@item
Don't declare unchecked exceptions in the @code{throws} clause of a
method.  However, if throwing an unchecked exception is part of the
method's API, you should mention it in the Javadoc.

@item
When overriding @code{Object.equals}, remember that @code{instanceof}
filters out @code{null}, so an explicit check is not needed.

@item
When catching an exception and rethrowing a new exception you should
``chain'' the Throwables.  Don't just add the String representation of
the caught exception.

@example
  try
    @{
      // Some code that can throw
    @}
  catch (IOException ioe)
    @{
      throw (SQLException) new SQLException("Database corrupt").setCause(ioe);
    @}
@end example

@item
Avoid the use of reserved words for identifiers.  This is obvious with those
such as @code{if} and @code{while} which have always been part of the Java
programming language, but you should be careful about accidentally using
words which have been added in later versions.  Notable examples are
@code{assert} (added in 1.4) and @code{enum} (added in 1.5).  Jikes will warn
of the use of the word @code{enum}, but, as it doesn't yet support the 1.5
version of the language, it will still allow this usage through.  A
compiler which supports 1.5 (e.g. the Eclipse compiler, ecj) will simply
fail to compile the offending source code.

@c fixme Describe Anonymous classes (example).
@c fixme Descibe Naming conventions when different from GNU Coding Standards.
@c fixme Describee API doc javadoc tags used.

@end itemize

Some things are the same as in the normal GNU Coding Standards:

@itemize @bullet

@item
Unnecessary braces can be removed, one line after an if, for, while as
examples.

@item
Space around operators (assignment, logical, relational, bitwise,
mathematical, shift).

@item
Blank line before single-line comments, multi-line comments, javadoc
comments.

@item
If more than 2 blank lines, trim to 2.

@item
Don't keep commented out code.  Just remove it or add a real comment
describing what it used to do and why it is changed to the current
implementation.
@end itemize


@node Hacking Code, Programming Goals, Programming Standards, Top
@comment node-name, next, previous, up
@chapter Working on the code, Working with others

There are a lot of people helping out with GNU Classpath.  Here are a
couple of practical guidelines to make working together on the code
smoother.

The main thing is to always discuss what you are up to on the
mailinglist.  Making sure that everybody knows who is working on what
is the most important thing to make sure we cooperate most
effectively.

We maintain a
@uref{http://www.gnu.org/software/classpath/tasks.html,Task List}
which contains items that you might want to work on.

Before starting to work on something please make sure you read this
complete guide.  And discuss it on list to make sure your work does
not duplicate or interferes with work someone else is already doing.
Always make sure that you submit things that are your own work.  And
that you have paperwork on file (as stated in the requirements
section) with the FSF authorizing the use of your additions.

Technically the GNU Classpath project is hosted on
@uref{http://savannah.gnu.org/,Savannah} a central point for
development, distribution and maintenance of GNU Software.  Here you
will find the
@uref{https://savannah.gnu.org/projects/classpath/,project page}, bug
reports, pending patches, links to mailing lists, news items and CVS.

You can find instructions on getting a CVS checkout for classpath at
@uref{https://savannah.gnu.org/cvs/?group=classpath}.

You don't have to get CVS commit write access to contribute, but it is
sometimes more convenient to be able to add your changes directly to
the project CVS. Please contact the GNU Classpath savannah admins to
arrange CVS access if you would like to have it.

Make sure to be subscribed to the commit-classpath mailinglist while
you are actively hacking on Classpath.  You have to send patches (cvs
diff -uN) to this list before committing.

We really want to have a pretty open check-in policy.  But this means
that you should be extra careful if you check something in.  If at all
in doubt or if you think that something might need extra explaining
since it is not completely obvious please make a little announcement
about the change on the mailinglist.  And if you do commit something
without discussing it first and another GNU Classpath hackers asks for
extra explanation or suggests to revert a certain commit then please
reply to the request by explaining why something should be so or if
you agree to revert it.  (Just reverting immediately is OK without
discussion, but then please don't mix it with other changes and please
say so on list.)

Patches that are already approved for libgcj or also OK for Classpath.
(But you still have to send a patch/diff to the list.)  All other
patches require you to think whether or not they are really OK and
non-controversial, or if you would like some feedback first on them
before committing.  We might get real commit rules in the future, for
now use your own judgment, but be a bit conservative.

Always contact the GNU Classpath maintainer before adding anything
non-trivial that you didn't write yourself and that does not come from
libgcj or from another known GNU Classpath or libgcj hacker.  If you
have been assigned to commit changes on behalf of another project or
a company always make sure they come from people who have signed the
papers for the FSF and/or fall under the arrangement your company made
with the FSF for contributions.  Mention in the ChangeLog who actually
wrote the patch.

Commits for completely unrelated changes they should be committed
separately (especially when doing a formatting change and a logical
change, do them in two separate commits). But do try to do a commit of
as much things/files that are done at the same time which can
logically be seen as part of the same change/cleanup etc.

When the change fixes an important bug or adds nice new functionality
please write a short entry for inclusion in the @file{NEWS} file.  If it
changes the VM interface you must mention that in both the @file{NEWS} file
and the VM Integration Guide.

All the ``rules'' are really meant to make sure that GNU Classpath
will be maintainable in the long run and to give all the projects that
are now using GNU Classpath an accurate view of the changes we make to
the code and to see what changed when.  If you think the requirements
are ``unworkable'' please try it first for a couple of weeks.  If you
still feel the same after having some more experience with the project
please feel free to bring up suggestions for improvements on the list.
But don't just ignore the rules!  Other hackers depend on them being
followed to be the most productive they can be (given the above
constraints).

@menu
* Branches::                    
* Writing ChangeLogs::          
@end menu

@node Branches, Writing ChangeLogs, Hacking Code, Hacking Code
@comment node-name, next, previous, up
@section Working with branches

Sometimes it is necessary to create branch of the source for doing new
work that is disruptive to the other hackers, or that needs new
language or libraries not yet (easily) available.

After discussing the need for a branch on the main mailinglist with
the other hackers explaining the need of a branch and suggestion of
the particular branch rules (what will be done on the branch, who will
work on it, will there be different commit guidelines then for the
mainline trunk and when is the branch estimated to be finished and
merged back into the trunk) every GNU Classpath hacker with commit
access should feel free to create a branch. There are however a couple
of rules that every branch should follow:

@itemize @bullet

@item All branches ought to be documented in the developer wiki at
@uref{http://developer.classpath.org/mediation/ClasspathBranches}, so
we can know which are live, who owns them, and when they die.

@item Some rules can be changed on a branch.  In particular the branch
maintainer can change the review requirements, and the requirement of
keeping things building, testing, etc, can also be lifted.  (These
should be documented along with the branch name and owner if they
differ from the trunk.)

@item Requirements for patch email to classpath-patches and for paperwork
@strong{cannot} be lifted. See @ref{Requirements}.

@item A branch should not be seen as ``private'' or
``may be completely broken''. It should be as much as possible
something that you work on with a team (and if there is no team - yet
- then there is nothing as bad as having a completely broken build to
get others to help out). There can of course be occasional breakage, but
it should be planned and explained. And you can certainly have a rule
like ``please ask me before committing to this branch''.

@item Merges from the trunk to a branch are at the discretion of the
branch maintainer.

@item A merge from a branch to the trunk is treated like any other patch.
In particular, it has to go through review, it must satisfy all the
trunk requirements (build, regression test, documentation).

@item There may be additional timing requirements on merging a branch to
the trunk depending on the release schedule, etc.  For instance we may
not want to do a branch merge just before a release.

@end itemize

If any of these rules are unclear please discuss on the list first.

@menu
* Writing ChangeLogs::          
@end menu

@node Writing ChangeLogs,  , Branches, Hacking Code
@comment node-name, next, previous, up
@section Documenting what changed when with ChangeLog entries

To keep track of who did what when we keep an explicit ChangeLog entry
together with the code.  This mirrors the CVS commit messages and in
general the ChangeLog entry is the same as the CVS commit message.
This provides an easy way for people getting a (snapshot) release or
without access to the CVS server to see what happened when.  We do not
generate the ChangeLog file automatically from the CVS server since
that is not reliable.

A good ChangeLog entry guideline can be found in the Guile Manual at
@uref{http://www.gnu.org/software/guile/changelogs/guile-changelogs_3.html}.

Here are some example to explain what should or shouldn't be in a
ChangeLog entry (and the corresponding commit message):

@itemize @bullet

@item
The first line of a ChangeLog entry should be:

@example
[date] <two spaces> [full name] <two spaces> [email-contact]
@end example

The second line should be blank. All other lines should be indented
with one tab.

@item
Just state what was changed.  Why something is done as it is done in
the current code should be either stated in the code itself or be
added to one of the documentation files (like this Hacking Guide).

So don't write:

@example
        * java/awt/font/OpenType.java: Remove 'public static final'
        from OpenType tags, reverting the change of 2003-08-11.  See
        Classpath discussion list of 2003-08-11.
@end example

Just state:

@example
        * java/awt/font/OpenType.java: Remove 'public static final' from
        all member fields.
@end example

In this case the reason for the change was added to this guide.

@item
Just as with the normal code style guide, don't make lines longer then
80 characters.

@item
Just as with comments in the code. The ChangeLog entry should be a
full sentence, starting with a captital and ending with a period.

@item
Be precise in what changed, not the effect of the change (which should
be clear from the code/patch).  So don't write:

@example
 * java/io/ObjectOutputStream.java : Allow putFields be called more 
 than once.
@end example

But explain what changed and in which methods it was changed:

@example
 * java/io/ObjectOutputStream.java (putFields): Don't call
 markFieldsWritten(). Only create new PutField when
 currentPutField is null.
 (writeFields): Call markFieldsWritten().
@end example

@end itemize

The above are all just guidelines.  We all appreciate the fact that writing
ChangeLog entries, using a coding style that is not ``your own'' and the
CVS, patch and diff tools do take some time to getting used to.  So don't