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

[Michael Koch]

On Sat, Apr 30, 2005 at 03:03:26AM +0200, Robert Schuster wrote:
> -----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);

I would prefer our own Error/Excpetion with preset text message. Otherwise
we will get a different message string all over depending on who wrote the
code.


Michael
-- 
Escape the Java Trap with GNU Classpath!
http://www.gnu.org/philosophy/java-trap.html

Join the community at http://planet.classpath.org/