From: pdenize@waikato.ac.nz
Newsgroups: comp.sys.acorn.advocacy,comp.sys.acorn
Subject: Validation of Acorns DesktopC includes
Date: 19 Aug 92 11:24:38 +1200
Organization: University of Waikato, Hamilton, New Zealand

I am getting VERY tired of the poor quality of the Desktop C libraries.  I don't
think a week has gone by where I haven't found another mistake, typo, or
negligent error.

The type of problems I refer to are as shown in two examples I have found in
the last 10 minutes:

First : Each module protects itself from multiple inclusion
-----------------------------------------------------------

Excerpt from an Acorn C include

#ifndef __drwaferror_h
#define __drawferror_h

-----------------------------------------------------------

This of course only works if you spell the defines correctly.  This error
should have been discovered during include file testing and validation.

Second: Comments to help the user follow the RiscOS style
----------------------------------------------------------

Excerpt from an Acorn C include

/* Error type.
 * Where a routine can produce an error, the actual value returned is a BOOL,
 * which is TRUE if the routine succeeded. The error itself is returned in a
 * block passed by the user; if NULL, then the details of the error are not
 * passed back.
 * The error block may contain either an operating system error, or an
 * internal error. In the latter case, it consists of a code and possibly a
 * pointer to the location in the file where the error occurred (if NULL,
 * the location is not known or not specified). By convention, this should
 * be reported by the caller in the form '<message> (location &xx in file)'.
 * For a list of codes and standard errors, see h.DrawErrors. The location is
 * relative to the start of the data block in the diagram.
 *
 */

----------------------------------------------------------

Note 1:
"By convention, this should be reported by the caller in the form 
'<message> (location &xx in file)'."

By which convention? (see !Draw)
What you might get is  -> Object size is too small at location &28
What you should get is -> Object size is too small (location &28 in file)

If Acorn can't follow these simple instructions, why should we?

I have examined four programs which use draw files:

#1: !Draw     (Acorn App Suite) .... Error format incorrect
#2: !DrawEx   (Acorn Desktop C) .... Ignores error then hangs RiscOS later
#3: !DrawPlus (J.Martin)        .... Error format incorrect & no message text
#4: !DrawView (G.Clements)      .... Error format incorrect & no message text

Small Note 2:
"For a list of codes and standard errors, see h.DrawErrors."

The file should be h.Drawferrors.

There are things worse than insufficient documentation: e.g.
  misleading, erroneous and poorly maintained documentation.


--------------------------------------------------------------------------

Many of the include files do not include the files they themselves need:
e.g. font.h can't be included without the client program first including
stddef.h.

Some definitions are defined twice so that if both files are included,
the compilation fails.

e.g. drawftypes.h and drawmod.h

Excerpt from Acorns drawftypes.h
-------------------------------

/* Types of join */

typedef enum
{ join_mitred   = 0,
  join_round    = 1,
  join_bevelled = 2
} draw_jointyp;


/* Types of cap specification */

typedef enum
{ cap_butt     = 0,
  cap_round    = 1,
  cap_square   = 2,
  cap_triangle = 3
} draw_captyp;

Excerpt from Acorns drawmod.h
----------------------------

/* Permissible join style values */

#define join_mitred    ((unsigned char)0x00)  /* mitred joins */
#define join_round     ((unsigned char)0x01)  /* round joins */
#define join_bevelled  ((unsigned char)0x02)  /* bevelled joins */

/* Permissible cap style values */

#define cap_butt       ((unsigned char)0x00)  /* butt caps */
#define cap_round      ((unsigned char)0x01)  /* round caps */
#define cap_square     ((unsigned char)0x02)  /* projecting square caps */
#define cap_triang     ((unsigned char)0x03)  /* triangular caps */

----------------------------------------------------------------------

It seems that even Acorn can't find these definitions in their own
documentation, so have developed them twice.

These errors should have been discovered during include file testing and
validation.  So it seems quite obvious that no validation, poor validation or
inadequate validation is performed on these expensive programming tools.  
With such poor tools, it is no wonder that products produced become
inconsistent with a defined style.

A simple validation should have detected many of the simple errors.

49 RiscOS include files
18 Standard include files

1) Each include should compile on its own.  Ensuring that all its
   requirements are included.

   This requires compiling a set of 67 one line programs

2) All includes should compile together.  Ensuring multiple declarations 
   have not been made.

   This requires a single 67 line program

3) Each include should be able to be included more than once.  Test 1 could 
   be extended to 67 two line programs where the second include is the same as
   the first.

   This requires compiling a set of 67 two line programs


How many of these tests does Acorn Desktop C libraries pass?

Test 1)  Failed 10 of the 67 programs.

Test 2)  3 errors, 4 serious errors, when all includes are compiled together.

Test 3)  Failed 11 of the 67 programs, but many may have been due to Test 1
         failures.


Paul Denize

--------------------------------------------------------------------------
Paul Denize                                Internet: PDenize@Waikato.ac.nz
Department of Computer Science
University of Waikato                         phone: ++64 7 8562-889
Hamilton                                                          Ext 8743
NEW ZEALAND                                   fax  : ++64 7 8560-135
--------------------------------------------------------------------------