libtool: Library tips
1
1 8 Tips for interface design
1 ***************************
1
1 Writing a good library interface takes a lot of practice and thorough
1 understanding of the problem that the library is intended to solve.
1
1 If you design a good interface, it won't have to change often, you
1 won't have to keep updating documentation, and users won't have to keep
1 relearning how to use the library.
1
1 Here is a brief list of tips for library interface design that may
1 help you in your exploits:
1
1 Plan ahead
1 Try to make every interface truly minimal, so that you won't need
1 to delete entry points very often.
1
1 Avoid interface changes
1 Some people love redesigning and changing entry points just for the
1 heck of it (note: _renaming_ a function is considered changing an
1 entry point). Don't be one of those people. If you must redesign
1 an interface, then try to leave compatibility functions behind so
1 that users don't need to rewrite their existing code.
1
1 Use opaque data types
1 The fewer data type definitions a library user has access to, the
1 better. If possible, design your functions to accept a generic
1 pointer (that you can cast to an internal data type), and provide
1 access functions rather than allowing the library user to directly
1 manipulate the data. That way, you have the freedom to change the
1 data structures without changing the interface.
1
1 This is essentially the same thing as using abstract data types and
1 inheritance in an object-oriented system.
1
1 Use header files
1 If you are careful to document each of your library's global
1 functions and variables in header files, and include them in your
1 library source files, then the compiler will let you know if you
1 make any interface changes by accident (⇒C header files).
1
1 Use the 'static' keyword (or equivalent) whenever possible
1 The fewer global functions your library has, the more flexibility
1 you'll have in changing them. Static functions and variables may
1 change forms as often as you like... your users cannot access them,
1 so they aren't interface changes.
1
1 Be careful with array dimensions
1 The number of elements in a global array is part of an interface,
1 even if the header just declares 'extern int foo[];'. This is
1 because on i386 and some other SVR4/ELF systems, when an
1 application references data in a shared library the size of that
1 data (whatever its type) is included in the application executable.
1 If you might want to change the size of an array or string then
1 provide a pointer not the actual array.
1
Menu