Debian Codegraph @

README.INTERFACES

raw
1 0) Summary
2
3 New code in aptitude should be written, wherever practical, with
4 fully abstract interfaces in .h files and hidden implementations in
5 .cc files.
6
7 1) Details
8
9 A standard abstract interface in aptitude looks like this:
10
11 class foo
12 {
13 public:
14 foo();
15 virtual ~foo();
16
17 virtual void method1(args...) = 0;
18 virtual void method2(args...) = 0;
19 // More methods ...
20
21 // Static constructor? (see below)
22 };
23
24 Note that both foo() and ~foo() are implemented in the .cc file.
25 foo() should be public so that any module can implement the foo
26 interface; this allows alternate implementations to be substituted
27 during testing.
28
29 Interfaces should contain only virtual methods, to aid multiple
30 inheritance, and they should generally derive only from other pure
31 virtual classes.
32
33 It might be tempting to derive from sigc::trackable, so signals can
34 be connected directly to interface methods. However, it is generally
35 better to either have the object connect itself (so the implementation
36 inherits trackable directly), or to connect the signal to a concrete
37 object that holds a strong reference to the interface. If you do
38 derive from trackable, please use virtual inheritance to avoid
39 unnecesary extra copies of "trackable" if an object implements several
40 interfaces.
41
42 1.1) Constructors
43
44 An abstract interface obviously can't be constructed.
45 Implementation classes should be hidden in .cc files and constructed
46 via either static methods on the interface, or free functions. Which
47 one is used depends on the relationship of the interface to the
48 implementation, as described below.
49
50 1.1.1) Single-implementation interfaces
51
52 Some interfaces in aptitude are only meant to have a single
53 implementation (except possibly for an implementation used just for
54 testing). These interfaces will expose their own creation via a
55 ::create() static member. If there are several overloads of the
56 object's constructor, you should use different names for each static
57 creation routine: create_empty(), create_full(), etc.
58
59 The create() routine will construct an instance of a class that is
60 only declared in the corresponding .cc file.
61
62 For instance:
63
64 // In foo.h:
65
66 class foo
67 {
68 // ... as above ...
69
70 static boost::shared_ptr<foo> create();
71 };
72
73 // In foo.cc:
74
75 class foo_impl : public foo
76 {
77 public:
78 // Declare implementations of private methods in foo:
79 void method1(args...);
80 // ...
81 };
82
83 void foo_impl::method1(args...) { /* ... */ }
84
85 boost::shared_ptr<foo> create()
86 {
87 return make_shared<foo>();
88 }
89
90 1.1.2) Multi-implementation interfaces
91
92 Interfaces which are meant to have several implementations are
93 defined in their own .h files, but without any constructor methods.
94 Instead, they are constructed via free functions. For instance:
95
96 // In foo.h:
97
98 class foo
99 {
100 // ... as above ...
101 };
102
103 // In bar.h:
104
105 boost::shared_ptr<foo> create_bar();
106
107 // In bar.cc:
108
109 class bar : public foo
110 {
111 // Declare implementations of methods in foo.
112 };
113
114 // Define implementations of methods in foo.
115
116 boost::shared_ptr<foo> create_bar()
117 {
118 return make_shared<bar>();
119 }
120
121 1.2) Signals and slots
122
123 Instead of directly exposing signal members, signals should be
124 exposed via appropriately-named routines. This provides better
125 encapsulation (directly exposing sigc signals allows external code to
126 invoke them) and makes it easier to test code that uses the
127 interfaces.
128
129 class foo
130 {
131 /** \brief Register a callback to be invoked when the hidden
132 * signal is invoked.
133 */
134 virtual sigc::connection connect_hidden(const sigc::slot<void> &slot) = 0;
135 };
136
137 Code in the src/qt tree can use the corresponding Qt idioms instead.
138
139 1.3) Mocks
140
141 By convention, mock implementations of interfaces should be placed
142 in a subdirectory mocks/ under the directory containing the .h of the
143 interface. The mock class has the same name as the interface, but
144 exists in a "mocks" namespace.
145
146 // In foo.h:
147
148 namespace aptitude
149 {
150 class foo
151 {
152 // Declarations of interface methods on foo.
153 };
154 }
155
156 // In mocks/foo.h:
157
158 namespace aptitude
159 {
160 namespace mocks
161 {
162 class foo : public aptitude::foo
163 {
164 // Mock out the methods of foo.
165 };
166 }
167 }
168
169 1.5) Global variables vs singleton classes vs static methods
170
171 Some functionality is truly global, and could be exposed via global
172 variables of class type, singleton classes with a hidden instance
173 variable, or static methods on a class.
174
175 Between these three approaches, singleton classes are preferred.
176 Using a singleton class behind an interface means that the
177 functionality can be swapped out, in test code if nowhere else. To
178 support this, it should be possible to pass in the interface as a
179 constructor parameter (although a convenience constructor that uses
180 the most common implementation of that interface is a good idea).
181
182 This is important because these modules represent access to system
183 functionality that might be awkward to use in test code. Existing
184 aptitude code violates this principle, with the result that it is
185 difficult to verify modules that use, for instance, the global
186 download cache or file queue.
187
188 1.6) Dependencies: constructor parameters vs created.
189
190 If an object accesses another object through an interface, it can
191 either take it as a constructor parameter or create it itself. Where
192 practical, it is preferred to pass it as a constructor parameter, to
193 make it possible to swap in different implementations of the
194 interface. However, it might be a good idea to provide a convenience
195 constructor that instantiates the most common implementations of the
196 interfaces that the class uses.
197
198 2) Motivation
199
200 Obviously, it is not necessary to use this many virtual interfaces.
201 There are a number of reasons that this approach is preferred:
202
203 2.1) Increasing testability
204
205 Unit tests are good. They let you verify your code up-front, and
206 they let you catch stealth changes to behavior early, before they
207 turn into bug reports. It's also difficult to write good unit
208 tests for complex pieces of code with many dependencies; you end
209 up testing the dependencies instead of the code you care about.
210
211 Breaking code into logically separated modules and dropping
212 abstraction layers between them makes it possible to separate
213 modules from the other code that they interact with. It also
214 makes it easy to test corner cases, particularly error
215 conditions, without having to generate synthetic system states
216 (for instance, what happens if the disk is full?), and it
217 provides a way of testing interactive code without requiring user
218 interaction (real or simulated).
219
220 2.2) Clear statements of internal interfaces
221
222 In a header file full of class definitions, with instance
223 variables, private methods, private member classes, and so on, it
224 can be tough to spot the actual interface methods. The coding
225 style described above places the public interface and (almost)
226 nothing else into the header file of a class.
227
228 I believe that this also leads to simpler interfaces, as it's
229 harder to hide poorly designed interface methods when they aren't
230 mixed with implementation concerns.
231
232 2.3) Fewer inter-header dependencies
233
234 Removing implementations from header files means that you don't
235 need to include the headers that are used by the implementation
236 from the header file. This can speed up compile times of client
237 code, in some cases significantly (for instance, when the
238 implementation requires some templates to be instantiated).
239 Furthermore, it means that modules using the interface don't have
240 to be recompiled just because the implementation changed, which
241 can speed up compiles significantly (old aptitude code was very
242 incestuous this way).
243
244 In extreme cases, this can break circular dependencies between
245 headers, although those tend to be signs that something e,se is
246 wrong anyway.