101 |
software design process. Steps listed above should produce documentation, |
software design process. Steps listed above should produce documentation, |
102 |
which records requirements or design decisions and could be used |
which records requirements or design decisions and could be used |
103 |
as reference manuals throughout the building of the software [#]_. In |
as reference manuals throughout the building of the software [#]_. In |
104 |
theory in an open software project new programmers are always free to |
theory in an open project new programmers are always free to |
105 |
participate independently. In practice a new programmer could need a lot |
participate independently. In practice a new programmer could need a lot |
106 |
of mentoring by other group members, before one could be productive for |
of mentoring by other group members, before one could be productive for |
107 |
the project. Sometimes sufficient mentoring could not even be possible, |
the project. Sometimes sufficient mentoring could not even be possible, |
108 |
because members open software projects could be geographically widely |
because members of such a projects could be geographically widely |
109 |
decentralized. This results the Mythical Man Month effect [#]_: adding a |
scattered. This results in the Mythical Man Month effect [#]_: adding a |
110 |
new member into software design process could rather delay than speed up |
new member into software design process could rather delay than speed up |
111 |
the project: |
the project: |
112 |
|
|
126 |
|
|
127 |
.. [#] brooks-mythical-man-month p.18 |
.. [#] brooks-mythical-man-month p.18 |
128 |
|
|
129 |
Eventually, the greater is the amount of programmers or higher turnover within |
Eventually, the greater is the amount of programmers or higher the turnover |
130 |
them, the more important is to have a good documentation. When new programmers |
within them, the more important it is to have a good documentation. |
131 |
|
When new programmers |
132 |
join the project they shouldn't have to depend completely on the old staff for |
join the project they shouldn't have to depend completely on the old staff for |
133 |
they information. An up-to-date and rational set of documents available for |
their information. An up-to-date and rational set of documents available for |
134 |
them could ameliorate the Mythical Man Month effect [#]_. |
them could ameliorate the Mythical Man Month effect [#]_. |
135 |
|
|
136 |
.. [#] parnas-clements-rational p.255 |
.. [#] parnas-clements-rational p.255 |
137 |
|
|
138 |
Because our group is doing experimental research, we need a flexible |
Because our group is doing experimental research, we need a flexible |
139 |
model for software development process. From the classical software |
model for software development process. From the classical software |
140 |
development process models, our one reminds most Boehm's spiral model |
development process models, ours reminds most of Boehm's spiral model |
141 |
of software development and enhancement [#]_. The spiral model |
of software development and enhancement [#]_. The spiral model |
142 |
is a cyclic and repeative model, where every cycle has the following |
is cyclic and repetitive, and every cycle has the following |
143 |
phases [#]_: |
phases [#]_: |
144 |
|
|
145 |
* determining objectives, alternatives, constraints |
* determining objectives, alternatives, constraints |
156 |
|
|
157 |
.. [#] beck99xp |
.. [#] beck99xp |
158 |
|
|
159 |
The nature of our software development process affects also strongly to |
The nature of our software development process affects also strongly |
160 |
our documentation needs. As we proceed by prototyping and enhancing our |
our documentation needs. As we proceed by prototyping and enhancing our |
161 |
software step by step, also our documentation should be updated in every |
software step by step, also our documentation should be updated in every |
162 |
cycle. Because the detailed implementation is in continual change, we prefer |
cycle. Because the detailed implementation is in continual change, we prefer |
163 |
to weight our documentation to more constant and general architectural |
to emphasis the more constant and general architectural |
164 |
documentation. Of course more detailed up-to-date documentation could be |
documentation. Of course, more detailed up-to-date documentation could be |
165 |
generated from the current source for those members, who are working with |
generated from the current source for those members who are working with |
166 |
particular details. Though, in general documentation rapidly changing details |
particular details. Though, in general documentation rapidly changing details |
167 |
would be irrelevant and confusing. Since currently the main purpose for our |
would be irrelevant and confusing. Since currently the main purpose for our |
168 |
documentation is to help intercommunication within our group, we believe manually |
documentation is to help intercommunication within our group, we believe manually |
169 |
made human abstracted documentation serving our purposes best. |
made human abstracted documentation serves our purposes best. |
170 |
|
|
171 |
Javadoc |
Javadoc |
172 |
------- |
------- |
173 |
|
|
174 |
**Javadoc** [#]_ is a hypertext documentation tool developed by Sun |
**Javadoc** [#]_ is a hypertext documentation tool developed by Sun |
175 |
Microsystems and delivered with Sun's Java distribution packages [#]_. |
Microsystems and delivered with Sun's Java Development Kit [#]_. |
176 |
Javadoc generates detailed and well crosslinked hypertext documentation |
Javadoc generates detailed and massively crosslinked hypertext documentation |
177 |
analyzing class hierarchies and including documentation comments from |
after analyzing class hierarchies and references, and includes documentation |
178 |
java source packages. Besides crosslinking, Javadoc creates indexes and |
comments from |
179 |
hierarchical trees as navigational aids for locating individual classes. |
java source code. Besides crosslinking, Javadoc creates alphabetical indexes |
180 |
|
and hierarchical trees to aid navigation into individual classes. |
181 |
|
|
182 |
``XXX Little more about Javadoc's history...`` |
``XXX Little more about Javadoc's history...`` |
183 |
|
|
186 |
.. [#] Java is a trademark of Sun Microsystems XXX Friendly, L. had |
.. [#] Java is a trademark of Sun Microsystems XXX Friendly, L. had |
187 |
a Java reference |
a Java reference |
188 |
|
|
189 |
Sun's distribution of Javadoc tools is proprietary, but there exists |
Sun's distribution of Javadoc tools is proprietary, but alternatives such as |
190 |
also free software (licensed unde GPL) alternatives like doc++ [#]_. |
doc++ [#]_ exist as free software (licensed under GPL). |
191 |
Doc++ is designed to create hypertext documentation also from sourcefile |
Doc++ is designed to create hypertext documentation from other languages |
192 |
of other languages (e.g. C, C++, perl). |
(e.g. C, C++, perl), in addition to Java. |
193 |
|
|
194 |
.. [#] http://docpp.sourceforge.net/ |
.. [#] http://docpp.sourceforge.net/ |
195 |
|
|
198 |
|
|
199 |
**Rational Rose** [#]_ is quite honored UML design tool. It provides a |
**Rational Rose** [#]_ is quite honored UML design tool. It provides a |
200 |
direct manipulation interface for drawing different kinds of UML diagrams |
direct manipulation interface for drawing different kinds of UML diagrams |
201 |
into it's data model, which is also supported by other products of Rational |
into its database, which is also supported by other products of Rational |
202 |
Software Corporations Rational product family. In addition of drawing |
Software Corporation's Rational product family. In addition to drawing |
203 |
diagrams from scratch, it allows reverse engineering diagrams from |
diagrams from scratch, it allows reverse engineering diagrams from |
204 |
code [#]_. |
code [#]_. |
205 |
|
|
206 |
Rational Rose could be used with **Rational Soda** [#]_ for creating more |
Rational Rose could be used with **Rational Soda** [#]_ to create more |
207 |
general architecture documentation. Soda is WYSIWYG (What You See Is What |
general architecture documentation. Soda is WYSIWYG (What You See Is What |
208 |
You Get) documentation writing tool which allows including diagrams and |
You Get) documentation writing tool, which allows including diagrams and |
209 |
documentation data from Rational Rose's data model within the written |
documentation data from Rational Rose's database to the written |
210 |
documentation. The both, Rational Rose and Rational Soda, are proprietary |
documentation. Both Rational Rose and Rational Soda are proprietary |
211 |
software and quite expensive for use of small research groups. Problems of |
software and quite expensive for use of small research groups. Problems of |
212 |
direct manipulation and WYSIWYG interfaces are discussed later. |
direct manipulation and WYSIWYG interfaces are discussed later. |
213 |
|
|
224 |
|
|
225 |
.. [#] http://www.lysator.liu.se/~alla/dia/ |
.. [#] http://www.lysator.liu.se/~alla/dia/ |
226 |
|
|
227 |
**Doxygen** [#]_ is an another Javadoc-like documentation tool, which generates |
**Doxygen** [#]_ is another Javadoc-like documentation tool, which generates |
228 |
hypertext documentation from source code of good variety of different languges. |
hypertext documentation from source code of good variety of different languges. |
229 |
An intresting feature in Doxygen is that it can also generates and embed |
An intresting feature in Doxygen is that it can also generate and embed |
230 |
UML diagrams representing software's class and inheritance hierarchies into |
into class documentation UML diagrams representing software's class and |
231 |
class documentation. Also the focused class is higlighted in diagrams on its |
inheritance hierarchies. |
232 |
documentation pages. Another enhancement for javadoc in Doxygen is that |
Also the focused class is higlighted in diagrams on its |
233 |
it creates dynamic shrinkable treeview for class hierarchy. |
documentation pages. Another enhancement to javadoc in Doxygen is that |
234 |
|
it creates a dynamic shrinkable treeview for class hierarchy. |
235 |
|
|
236 |
.. [#] http://www.doxygen.org/ |
.. [#] http://www.doxygen.org/ |
237 |
|
|
238 |
**MetaPhor** [#]_ Project group in University of Jyväskylä have |
**MetaPhor** [#]_ Project in University of Jyväskylä have |
239 |
looked for ways of using hypertext in CASE tools [#]_. Results of its research |
looked for ways of using hypertext in CASE tools [#]_. Results of its research |
240 |
have been used in **MetaEdit+** [#]_ meta CASE tool developed by MetaCase |
have been used in **MetaEdit+** [#]_ meta CASE tool developed by MetaCase |
241 |
Consulting. MetaEdit+ provides bi-directional linking between all its objects |
Consulting. MetaEdit+ provides bi-directional linking between all its objects |
242 |
and interface for reaching linking contexts from diagrams' objects. |
and an interface for reaching linking contexts from diagrams' objects. |
243 |
|
|
244 |
: XXX This should be checked, but metaphor.it.jyu.fi seems to be down :( ] |
: XXX This should be checked, but metaphor.it.jyu.fi seems to be down :( ] |
245 |
|
|
291 |
view it is still ridiculous even talk about generating the design documentation; the |
view it is still ridiculous even talk about generating the design documentation; the |
292 |
design should always be made by human, and if the design documentation is for human |
design should always be made by human, and if the design documentation is for human |
293 |
reading, it should be also human made. What we could do, is lower the treshold of |
reading, it should be also human made. What we could do, is lower the treshold of |
294 |
writing the design documentation. |
getting into writing the design documentation. |
295 |
|
|
296 |
For detailed documentation we have selected using Javadoc, since even it's |
For detailed documentation we have decided to use Javadoc, since even though |
297 |
not open software it's still free and quite easy to use. Also the likeness of |
it's |
298 |
|
not free software it's still usable for free and quite easy to use. Also the likeness of |
299 |
documentation with most of the other Java based projects is a significant issue. |
documentation with most of the other Java based projects is a significant issue. |
300 |
A more difficult issue is to select tools for writing the design documentation and |
A more difficult issue is to select tools for writing the design documentation and |
301 |
drawing diagrams into it. The solution should be cheap, and as an open software |
drawing diagrams into it. The solution should be cheap, and as a free software |
302 |
project we would prefer other free software. Also the solution should fit well |
project we would prefer other free software. Also the solution should fit well |
303 |
to our current working customs. |
to our current working customs. |
304 |
|
|
305 |
In addition to the tool selection problem we have to problem of two distinct |
In addition to the tool selection problem we have to problem of two distinct |
306 |
documentation: the human written design documentation and automaticly generated |
pieces of documentation: the human written design documentation and the |
307 |
|
automatically generated |
308 |
detailed Javadoc documentation. During coding the Javadoc documentation is |
detailed Javadoc documentation. During coding the Javadoc documentation is |
309 |
often necessary, but the architectural design documentation could be easily left |
often necessary, but the architectural design documentation could be easily left |
310 |
in the dark reaches of the filesystem. It could be argued that architectural |
in the dark reaches of the filesystem. It could be argued that the reason for |
311 |
documents are left unused, because relevant parts linked to ongoing work are |
architectural |
312 |
hard to find. The two distinct documentation (javadoc and design documentation) |
documents being left unused is that relevant parts linked to ongoing work are |
313 |
cannot seen as whole. Therefore we should make them work as a whole. |
hard to find. The distinct pieces (javadoc and design documentation) |
314 |
|
cannot seen as a whole. Therefore we should make them work as a whole. |
315 |
|
|
316 |
"Obvious" question: can we increase the overall value by interconnecting the |
"Obvious" question: can we increase the overall value by interconnecting the |
317 |
two distinct documentations? |
two distinct pieces of documentation? |
318 |
|
|
319 |
When looking at a design document, jumping to the javadocs to get the details |
When looking at a design document, jumping to the javadocs to get the details |
320 |
would be useful, and when looking at a Javadoc, it would be useful |
would be useful, and when looking at a Javadoc, it would be useful |
321 |
to be able to see if any design documents refer to that class. |
to be able to see if any design documents refer to that class. |
322 |
We believe that the architecture document will be read more, after it's |
We believe that the architecture document will be read more, after it's |
323 |
it's easily reachable from relevant parts of Javadoc. |
easily reachable from relevant parts of Javadoc. |
324 |
This is the starting point for the toolchain developed in this article. |
This is the starting point for the toolchain developed in this article. |
325 |
|
|
326 |
|
|