-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Hi,
after a discussion on IRC about the latest issue on unrealistic code
paths we decided to make it a requirement to mark them with exceptions.
This update to hacking.texinfo describes that.
> 2005-04-30 Robert Schuster <[EMAIL PROTECTED]>
>
> * doc/hacking.texinfo: Added section about dealing with
> unrealistic code paths.
Is that OK for everyone?
cu
Robert
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org
iD8DBQFCctleG9cfwmwwEtoRAv05AJ9eGEGw9zj52UBvlSBxrhVQEY25mQCgkkuM
x2PEyC7utEqv2eTGKq1YO/4=
=TmKd
-----END PGP SIGNATURE-----
Index: doc/hacking.texinfo
===================================================================
RCS file: /cvsroot/classpath/classpath/doc/hacking.texinfo,v
retrieving revision 1.34
diff -u -r1.34 hacking.texinfo
--- doc/hacking.texinfo 27 Mar 2005 15:38:38 -0000 1.34
+++ doc/hacking.texinfo 30 Apr 2005 00:51:57 -0000
@@ -11,7 +11,7 @@
This file contains important information you will need to know if you
are going to hack on the GNU Classpath project code.
-Copyright (C) 1998,1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
+Copyright (C) 1998,1999,2000,2001,2002,2003,2004,2005 Free Software Foundation, Inc.
@ifnotplaintext
@dircategory GNU Libraries
@@ -28,6 +28,7 @@
@author John Keiser
@author C. Brian Jones
@author Mark J. Wielaard
[EMAIL PROTECTED] Robert Schuster
@page
@vskip 0pt plus 1filll
@@ -480,9 +481,10 @@
@menu
* Source Code Style Guide::
+* Dealing with unrealistic code paths::
@end menu
[EMAIL PROTECTED] Source Code Style Guide, , Programming Standards, Programming Standards
[EMAIL PROTECTED] Source Code Style Guide, Dealing with unrealistic code paths, Programming Standards, Programming Standards
@comment node-name, next, previous, up
@section Java source coding style
@@ -711,6 +713,51 @@
implementation.
@end itemize
[EMAIL PROTECTED] Dealing with unrealistic code paths, , Source Code Style Guide, Programming Standards
[EMAIL PROTECTED] node-name, next, previous, up
[EMAIL PROTECTED] Unrealistic code paths
+
+As the paper at @uref{http://www.psgd.org/paul/docs/canthappen.html} suggests
+one should avoid thinking that there is something like an unrealistic
+code path. This section presents how we decided to deal with that.
+
+We consider something an unrealistic code path when it does something like this
+(from javax.swing.JTextArea):
+
[EMAIL PROTECTED]
+try
[EMAIL PROTECTED]
+ getDocument().insertString(getText().length(), toAppend, null);
[EMAIL PROTECTED]
+catch (BadLocationException exception)
[EMAIL PROTECTED]
+ // This cannot happen as we check offset above.
[EMAIL PROTECTED]
[EMAIL PROTECTED] example
+
+Following the Java semantics the BadLocationException will never be thrown but
+what if the runtime's JIT compiler emitted wrong code in that situation?
+Do not forget that a lot of software is needed to get a piece of Java bytecode
+to run and all that software may have bugs. Therefore code it like this:
+
[EMAIL PROTECTED]
+try
[EMAIL PROTECTED]
+ getDocument().insertString(getText().length(), toAppend, null);
[EMAIL PROTECTED]
+catch (BadLocationException exception)
[EMAIL PROTECTED]
+ /* This shouldn't happen in theory -- but, if it does... */
+ throw new InternalError("Unexpected exception occurred.", exception);
[EMAIL PROTECTED]
[EMAIL PROTECTED] example
+
+When a completely abnormal situation happens you should use InternalError
+because it will indicate that something is seriously broken.
+
+Please note that there are many occurances in GNU Classpath where we were not
+strict with this requirement. You are encouraged to fix the issues whenever
+you see them.
@node Hacking Code, Programming Goals, Programming Standards, Top
@comment node-name, next, previous, up
_______________________________________________
Classpath-patches mailing list
Classpath-patches@gnu.org
http://lists.gnu.org/mailman/listinfo/classpath-patches
