Re: How to Design an Application Programmers' Interface (API)

[Gregory Pietsch <gkp1@flash.net>]

"E. Robert Tisdale" wrote:
> 
> The ANSI C computer programming language
> does not support Object Oriented Programming very well.

Of course not.  It was never an OOP language.

> It has an encapsulation mechanism (struct) for creating new types
> and a mechanism (typedef) for creating synonyms for existing types
> but it doesn't really provide any mechanism
> for hiding the data members of a struct except for opaque data types.

Yawn... That's because we C programmers don't even WANT any mechanism
for hiding the data members.

> The definition of an opaque data type
> is never exposed to the application program
> so the only way to create, manipulate and destroy opaque data types
> is by passing pointers to library functions.
> This means that memory for all opaque data types
> must be allocated from free storage (on the heap)
> which can involve significant overhead for small objects.

e.g. FILE in <stdio.h>.

> Another, less effective, method
> for hiding the private data members of a struct in ANSI C
> is to provide the application program with a dummy type definition
> 
>         typedef struct {
>           int dummy[new_type_size/sizeof(int)];
>           } new_type;
> 
> which is the same size as the new type
> but conceals the name and location of all private data members.
> The advantage of dummy type definitions is that memory for them
> may be allocated from automatic storage (on the stack)
> with virtually no overhead.

In other words, a union of the real type with an array of int (or char)
the same size?  What fun.

> 
> The problem with opaque data types and dummy type definitions is that
> none of the functions that create, manipulate and destroy them
> can be implemented as inline functions or C preprocessor macros.
> This problem is solved by using library functions
> together with opaque data types or dummy type definitions
> during program development, debugging and testing
> then, just before placing the application into service,
> the private type definition is substituted
> for the opaque or dummy data type definition,
> the inline functions and/or C processor macros are substituted
> for the external library functions
> and the application program is recompiled.

Seems a little complicated.  Why don't I just write the program?

> The advantage of using the external library functions
> during application program development, debugging and testing
> is that application programs usually compile faster
> if they don't need to process inline functions or C preprocessor macros
> and the compiler can diagnose programming errors more precisely.

> Application programmers must NOT be obliged
> to access private data members directly.

Fine.  Whenever I write C++ programs, I'll avoid adding get/set methods.

> The library must provide functions
> which application programmers can use
> to create, manipulate and destroy objects as efficiently as possible.

Don't have a problem with that.
 
> If the library API fails to specify such functions
> and programmers write applications
> which access private data members directly,
> library developers will never be able to change
> the actual data representation,
> the meaning of any data member
> or even the name of any data member
> without breaking existing application programs.
> But, if the library API specifies such functions
> and library developers make a reasonable attempt
> to hide the actual type definition and private data members
> so that applications programmers can't access them directly by accident,
> then library developers are at liberty to change the data representation,
> including the meaning, location, name and number of data members
> at any time just by redefining the library functions
> that access them directly and redistributing the library.

This is getting into OO philosophy more than anything.

Later, Gregory Pietsch