Re: Patch: FYI: more standards updates

[Tom Tromey]

I'm checking in the appended.  This updates the hacking documentation
to take into account some things Eric pointed out.

Eric> Other ideas: Do we have a preferred order for declarations?  For
Eric> example, some classes list fields, constructors, methods, then nested
Eric> classes; and either sort alphabetically or follow the order they are
Eric> documented in Sun's API documentation.

I don't think we have an agreed-upon rule here.

Tom

Index: ChangeLog
from  Tom Tromey  <address@hidden>

        * doc/hacking.texinfo (Programming Standards): Added more
        guidelines.

Index: doc/hacking.texinfo
===================================================================
RCS file: /cvsroot/classpath/classpath/doc/hacking.texinfo,v
retrieving revision 1.15
diff -u -r1.15 hacking.texinfo
--- doc/hacking.texinfo 9 Jan 2004 20:55:58 -0000 1.15
+++ doc/hacking.texinfo 30 Jan 2004 23:27:00 -0000
@@ -386,15 +386,35 @@
 @end example
 
 @item
-Don't use redundant modifiers.  For instance, all members of an
-interface are implicitly @code{public}, so there is no need to
-explicitly declare them as @code{public}.
+Don't use redundant modifiers.  Here is some sample code that shows
+redundant modifiers in comments:
+
address@hidden
+/*abstract*/ interface I {
+   /*public abstract*/ void m();
+   /*public static final*/ int i = 1;
+   /*public static*/ class Inner {}
+}
+final class C {
+   /*final*/ void m() {}
+}
address@hidden example
+
+Note that Jikes will generate warnings for these if you use
address@hidden on the command line.
+
address@hidden
+Modifiers should be listed in the standard order recommended by the
+JLS.  Jikes will warn for this when given @code{+Pmodifier-order}.
 
 @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}.
+declared as @code{private static final}.  Note that a class may be
address@hidden 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
 
@@ -402,6 +422,10 @@
 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.
+
address@hidden
+When overriding @code{Object.equals}, remember that @code{instanceof}
+filters out @code{null}, so an explicit check is not needed.
 
 @end itemize