Some comments about Programming Guidelines White Paper

[Laurent Gauthier <lolo gothic remcomp fr>]

Hi Miguel and Federico,

I'm really interested in the work you are currently doing on the
programming guidelines white-paper for the GNOME project.  I've some
remarks on the current document based on notes I'd written about
developing reliable software, and good programming practice.

Here are some things that I think could be added to the document, let
me know what you think.

* About robustness:

  We sould try to define the expectations users can have with
  respect to software reliability and security (a kind of user's bill
  of rights).  This could help as a basis for decisions to be made
  during software development.

  Here is my proposal:

   The user of a GNOME application should be able to get the following 
   services:

   * The program must never fail silently.

     From an end user perspective a program must never fail silently. A
     silent failure is very disturbing because:

     + the user will consider the tools as not reliable.
     + no clear bug report is possible for a novice user.
     + you are doing bad PR for the whole environment.

     COMMENT: from my personnal experience fvwm95 is really bad
       example for this.  When a menu entry for it is buggy and the
       command fails to start it is VERY difficult for an end-user
       to discover that something has gone wrong, and to determine
       why.  The GNOME panel was not really good on this point also in
       my last experience. 

   * In case of failure:

     + If the failure is due to a supposed problem in your code, prompt the
     user with the best info you can and ask him to report a bug in a
     civil manner.

     COMMENT: there should be a section in the help system about reporting 
     bugs, and helping novice users to do useful reports. 

     + If the failure is due to a bad setup by the user then tell him about
     that and give him a pointer on where to look to get things right (in 
     end-user language).  This could be done by displaying a dialog
     showing a error or warning dialog, and inviting the user to click 
     on a "Help" button to get more info.
 
     Extra bonus is given if you implement a fail-safe (degraded) mode
     in your application, that will allow the application to start
     anyway.

     COMMENT: the release 1.0 of GNOME was from this point of view a
     bad example.  A lot of people have been complaining about it as
     being a buggy release when some problems were caused by ~/.gnome
     leftovers from previous installations.  Nicholas Petreley for
     example has been explaining this in one of his articles.

   * Do not lock a user in a loop of cascading events because of 
     errors. The user will consider the tool not only buggy, but also
     annoying!

     COMMENT: I have two bad experiences to relate here that will help 
     you understand what I mean.

     Example 1: The Gimp

	* I was trying to save a picture with the Gimp and the
          filesystem was full. The application created approximatively 
          30 to 50 error dialogs that I had to close by hand later...

          This happened just because the error was not caught
          correctly ONCE!  This, for an end user, is REALLY annoying.

     Example 2: GMC

        * I had installed on my Debian system GNOME 1.0 from rpms
        found on a CD, but the installation of GMC was not done
        correctly (by me).  What happened is that GMC failed to setup
        the desktop, showing me a dialog explaining this to me (this is
        the fine part), and insisted that I fixed the problem before
        going further.  Whatever I could do (click OK or Cancel in the
        dialog) GMC was restarting itself (as I understood it) and
        showing the same error dialog again and again.

        There were 3 problems there in my point of view:
        * Strong feeling of being locked in an endless loop of errors.
        * No pointers on help documentation of how to fix the problem.
        * No easy way to start the file-manager in a failure safe mode.

        NOTE: this is not a bug report, it's just an example to
              illustrate some things really important to end users.

   * Consistent error reporting is also important.  Maybe there should be 
     something about that in the GNOME libs to have common dialogs for 
     error reporting.

   * Handle exceptionnal events in a sane way, and test the handling
     of such situations.  This is where the user will appreciate the
     reliability of your software!

     Do some basic failure testing on your application:

     + File system full.
     + Configuration files corrupted.
     + Network connection broken if your application is dependent on
       network.
     + Kill you X server (yeah I know this is extreme, but some
       programs managed to kill it. testgtk did it when playing with
       pixmaps).
     + Kill your application using the various UNIX signals that are
       available.
     + Kill your application with the help of your window manager.

  Robustness and correctness is also about the way the end-user is
  interacting with the application.  The behavior of the application
  must sane (UNDERSTANDABLE, SYNTHETIC and HELPFUL) from the point of
  view of the user when things are going wrong.


* About security:

  You could suggest some good readings about programming and
  security, in particular I think one good paper to get the ideas
  right is "Murphy's law and computer security" by Wietse Venema that
  you'll find there:

    http://www.fish.com/security/murphy.html

  Other papers there (http://www.fish.com/security/) may be of interest.

Again, let me know what you think.

Bye, Laurent.
-- 
Laurent.Gauthier@gothic.remcomp.fr +;+ ``Keep it simple: as simple as possible,
             at home               ;:;   but no simpler.''                    
        in Nozay (France)          +;+                          -- A. Einstein