[cp-patches] RFC: hacking guide - unrealistic code paths

[Robert Schuster]

-----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  <address@hidden>
> 
>     * 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
address@hidden Robert Schuster
 
 @page
 @vskip 0pt plus 1filll
@@ -480,9 +481,10 @@
 
 @menu
 * Source Code Style Guide::     
+* Dealing with unrealistic code paths::
 @end menu
 
address@hidden Source Code Style Guide,  , Programming Standards, Programming 
Standards
address@hidden 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
 
address@hidden Dealing with unrealistic code paths, , Source Code Style Guide, 
Programming Standards
address@hidden node-name, next, previous, up
address@hidden 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):
+
address@hidden
+try
address@hidden
+       getDocument().insertString(getText().length(), toAppend, null);
address@hidden
+catch (BadLocationException exception)
address@hidden
+       // This cannot happen as we check offset above.
address@hidden
address@hidden 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:
+
address@hidden
+try
address@hidden
+       getDocument().insertString(getText().length(), toAppend, null);
address@hidden
+catch (BadLocationException exception)
address@hidden
+       /* This shouldn't happen in theory -- but, if it does...  */
+       throw new InternalError("Unexpected exception occurred.", exception);
address@hidden
address@hidden 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