docs/develop/ikteam/IK_Process.html

   1 <html>
   2 <Title>Interface Kit Team Process</Title>
   3 <body>
   4 <h1>Interface Kit Team Process</h1>
   5 <p>
   6 This paper deals with the set of requirements for reimplementing any portion of the BeOS
   7 covered by the Interface Kit team's charter; namely, the Interface Kit, the Application
   8 Kit, the app_server, and related preferences applets. &nbsp; This team's resposibilities
   9 may broaden later to include more areas of the OS which are related (the input_server
  10 comes to mind as a possibility). &nbsp; Since the mandate of the group covers such a
  11 large and public (from a 3rd party developer's perspective) portion of BeOS -- a portion
  12 that is central to the user and developer experience of BeOS -- it is vital that our work
  13 be done in a scrupulously documented and tested fashion. &nbsp; This paper lays out the
  14 process which, when adhered to, aims to ensure this high standard of documentation and
  15 testability.
  16 </p><p>
  17 First, a definition of "module" as it pertains to this paper.
  18 <p>
  19 <b>Module:</b>
  20 A function, class, kit, application or related set of functions, classes, kits or
  21 applications is refered to as a "module" in this paper, the implication being that
  22 there can be modules within modules. &nbsp; A module is any specifiable and testable
  23 entity -- which may or may not rely on other modules to accomplish its functionality.
  24 </p><p>
  25 <h2>
  26 Process Requirements
  27 <hr align="left" width="25%">
  28 </h2>
  29
  30 Each module in this project shall have the following items:
  31 <ul>
  32         <li>Complete interface specification. &nbsp; For kits, this will mostly come
  33                 from the BeBook, but in many cases the specification will have to elaborate
  34                 on what the BeBook provides or even be created entirely (app_server internals
  35                 are a good example).</li>
  36         <li>Complete use case specification. &nbsp; For those not familiar with use cases,
  37                 they consist of the following:
  38                 <ul>
  39                         <li>A list of ways in which a module is expected to be used</li>
  40                         <li>Sublists of assumptions/prerequisites for each of those cases. &nbsp;
  41                                 This should include items such as state of an object instance at the
  42                                 time of method invocation, the state of parameters passed to functions,
  43                                 etc.</li>
  44                         <li>Sublists of error conditions and handling for each case where
  45                                 assumptions/prerequisites are not properly met. &nbsp; This list should
  46                                 not attempt to be all inclusive: &nbsp; circumstances that do not
  47                                 directly bear upon the assumptions/prerequisites do not need to be
  48                                 considered unless clearly necessary.</li>
  49                 </ul></li>
  50         <li>A set of unit tests which verify that the module performs correctly in expected
  51                 use cases as well as under error conditions as described in the use case
  52                 specification.</li>
  53         <li>A plain-english discussion of how the module implements its functionality: &nbsp;
  54                 what algorithms are to be used, what other modules are relied upon, the general
  55                 design rationale, execution flow, etc.</li>
  56         <li>The actual reimplementation.</li>
  57 </ul>
  58
  59 Each of the above items is to be completed roughly in the order listed. &nbsp; In other
  60 words, a given module should have a complete interface specification, etc., before it is
  61 reimplemented. &nbsp; Prototyping is encouraged, of course. &nbsp; For existing APIs, the
  62 recommended course is to write the interface spec, use case spec and unit tests to the
  63 API. &nbsp; Unit tests, in particular, should perform as expected when run against the
  64 existing API. &nbsp; When they do not, changes may need to be made to the specifications.
  65 &nbsp; Our goal is to reimplement the APIs as they are, not necessarily as they're
  66 documented -- and then ensure that the docs accurately reflect the reimplementation.
  67 &nbsp; Thorough testing of the existing implementation will show us where the
  68 documentation is wrong, misleading or absent, thereby helping to ensure that our
  69 reimplementation is functionaly identical to the existing one.
  70 <p>
  71 <a href="http://www.xprogramming.com/ftp/TestingFramework/CppUnit/CppUnit15.zip">
  72 CppTest</a>
  73 is the test framework we will be using. &nbsp; By using this framework for all our unit
  74 tests, we can easily build large test suites which will verify the codebase in a single
  75 executed run. &nbsp; An excellent short discussion of the value of unit tests is here:<br>
  76
  77 <a href="http://www.extremeprogramming.org/rules/unittests.html">
  78 http://www.extremeprogramming.org/rules/unittests.html</a>
  79
  80 <h2>
  81 A Suggestion
  82 <hr align="left" width="25%">
  83 </h2>
  84
  85 Although the interface specification for each module should be completed first, I have a
  86 suggestion for how to proceed from there which should make the remainder of the process
  87 less boring. &nbsp; Rather than following the interface specification with a full set of
  88 use cases followed by a full set of tests, a more productive and enjoyable way to go is
  89 to take each module in turn, write one of the use cases/error conditions for it and
  90 immediately write the test for that use case/error condition. &nbsp; This will break up
  91 the tedious process of specifying all the use cases and error conditions with a bit of
  92 coding -- not implementation code, but code nonetheless.
  93
  94 <h2>
  95 Some Final Thoughts
  96 <hr align="left" width="25%">
  97 </h2>
  98
  99 This process is a very rigorous approach to take. &nbsp; Given that our goal is to produce
 100 the most stable, robust and professional desktop operating system available, this sort of
 101 thoroughness is justifiable and necessary. &nbsp; Our understanding of the system will be
 102 greatly increased and the task of coming up to speed on the system will be made much
 103 easier for outsiders and newcomers to the project.
 104 <p>
 105 This approach is also not the most "fun": &nbsp; sitting down and hacking out code has the
 106 attraction of instant gratification that design work does not. &nbsp; It is important to
 107 understand, however, that proper design work done up front makes the task of
 108 implementation easier, the chore of integration much less onerous and testing and
 109 code verification a snap. &nbsp; Provided we do not get locked in "analysis paralysis"
 110 and attack the design work as vigorously as the coding work, the entire project will
 111 actually move more quickly -- usually quite a bit more quickly -- than if we had simply
 112 started coding. &nbsp; Thrown away versions of the codebase should be just that:
 113 &nbsp; quick prototypes intended to be disposable, rather than full-blown implementation
 114 attempts which fail or are mysterious blackboxes because we don't really understand the
 115 module. &nbsp; Following this process makes it far more likely that when we sit down to
 116 do a module implementation, the first try will be the last (bug fixes not withstanding,
 117 of course ;).
 118 </p><p>
 119 To ensure the process is followed and we produce the highest quality code we can, code
 120 will not be accepted for release until all of the process items are covered. &nbsp; If
 121 this seems like a hardline stance to take, remember: &nbsp; every single app which
 122 utilizes the Application and Interface Kits relies on our code to be rock solid --
 123 totally predictable and completely reliable. &nbsp; Let's strive to be engineers, not
 124 h4X0rz.
 125 </p>
 126 <hr>
 127 <!-- The obligatory SourceForge plug -->
 128 <center>
 129 <small>The OpenBeOS project is hosted by:</small><br><br>
 130 <a href="http://sourceforge.net">
 131 <img src="http://sourceforge.net/sflogo.php?group_id=33869&type=1" width="88" height="31" border="0" alt="SourceForge Logo">
 132 </a>
 133 <p>
 134
 135 <small>Copyright &copy; 2001-2002
 136 <a href="http://www.openbeos.org">OpenBeOS</a> Project</small>
 137 </center>
 138
 139 </body>
 140 </html>