1
2
3
4                          API Additions to Widgets
5                          ========================
6
7
8
9
10When designing Widgets, the idea is to provide a full set of API's to allow
11developers to manipulate it.  Sometimes, new API's may need to be added if
12the initial implementation of some Widget didn't implement a complete set.
13
14Everybody always wants their favorite function implemented in the library,
15because it would make *their* job easier.  Thus, the temptation exists to keep
16adding ``useful'' little functions, just to satisfy everybody.
17
18There are several reasons why this is a bad idea:
19
20
21  - Lots of small ad-hoc functions will make a Widget much harder for
22    everybody to learn.
23
24  - Since a Widget implements a certain abstraction, adding lots of functions
25    will make it harder to maintain the simplicity of the abstraction.
26
27  - Lots of functions will also make it more difficult to keep the software
28    implementation consistent.
29
30  - It will make it harder to reach a point of ``closure'' i.e. one keeps
31    adding things, instead of attaining completeness.
32
33
34To curb wild-growth in API's, we prefer to add API's judiciously.  In order for
35a function to be added to the library, one should demonstrate:
36
37
38  - That the utility of this new function appeals to a large audience.
39
40  - The function fills a real gap in functionality.
41
42  - The function adds functionality that existing API's are unable to provide.
43
44  - The new function does not break the abstraction that the Widget provides.
45
46  - Appropriate rationale for its inclusion can be given. [This has to be a
47    better argument than: ``Because I need it!''].
48
49
50Goals for Widget API's should be:
51
52
53  1) Orthogonality.  This augments transferability of knowledge from one
54     situation to the next.
55
56  2) Predictability.  Naming should strongly reflect function.  Functions
57     should have no side-effects not reflected in the name; preferably,
58     one function should do one thing only.
59
60  3) Symmetry.  This means for example every ``set'' function should have a
61     corresponding ``get,'' every ``open'' should have a ``close'' and so on.
62
63  4) Completeness.  All parameters can be accessed, and all features of the
64     Widget can be used, without any need for backdoors etc.
65
66  5) Minimality.  A set of API's is minimal if one can not take away anything
67     without making the API incomplete.  Minimality makes it much easier to
68     maintain consistent state in the Widget.
69
70  6) Philosophical fit.  The FOX library has been developed with certain
71     underlying paradigms, both in concept as well as in implementation; API's
72     should adhere to these, as deviation from them will make things less
73     easy to understand, or less easy to extend.
74
75  7) Wide Appeal.  When convenience API's are added, it must be true that these
76     functions have broad appeal, i.e. expected to be used by a large fraction
77     of the library's users.
78
79