304 |
UML Diagrams |
UML Diagrams |
305 |
------------ |
------------ |
306 |
|
|
307 |
The Unified Modeling Language (UML) is the standard way to visually |
The Unified Modeling Language (UML) is the standard way to |
308 |
describe software constructs in diagrams |
visually |
309 |
|
describe software architectures and constructs in diagrams |
310 |
[booch-jacobson-rumbaugh98uml-user-guide]_. It was originally |
[booch-jacobson-rumbaugh98uml-user-guide]_. It was originally |
311 |
developed for descriptions on an abstract level (many constructs |
developed for descriptions on an abstract level (many constructs |
312 |
cannot be directly expressed in any programming language) |
cannot be directly expressed in any programming language) |
349 |
The problem of two separate bodies of documentation |
The problem of two separate bodies of documentation |
350 |
=================================================== |
=================================================== |
351 |
|
|
352 |
In our project, as probably in most projects that use the Java programming |
In our software engineering project[gzz]_, as probably in most projects that use the Java programming |
353 |
language [java-ref]_, the software development documentation is |
language [java-ref]_, the software development documentation is |
354 |
divided into two separate domains: the design documentation and |
divided into two major domains: the design documentation and |
355 |
Javadoc [friendly95javadoc]_. The design documents cover the most |
Javadoc [friendly95javadoc]_. The design documents cover the most |
356 |
important architectural features and are written either before coding |
important architectural features and are written either before coding |
357 |
(for design) or after (for exposition or of the architecture or refactoring design). |
(for design) or after (for exposition or of the architecture or refactoring design). |
403 |
necessary, but the design documentation is easily left in the |
necessary, but the design documentation is easily left in the |
404 |
dark reaches of the filesystem. It could be argued that the reason for |
dark reaches of the filesystem. It could be argued that the reason for |
405 |
design documents being left unused is that relevant parts linked to |
design documents being left unused is that relevant parts linked to |
406 |
ongoing work are hard to find. The distinct pieces (Javadoc and the |
ongoing work are hard to find. |
407 |
design documentation) cannot seen as a whole. Therefore we should make |
|
408 |
them work better as a whole. |
For example, when referring to the Javadoc on how to use some API, |
409 |
|
one often comes across an interface which is of the type that |
410 |
|
one would like to obtain from somewhere, but unless someone |
411 |
|
has explicitly written the instructions into the doc comments, |
412 |
|
the Javadoc will only explain how the interface is used. |
413 |
|
What is exasperates this situation is the certainty |
414 |
|
that in the architectural document, there surely is a diagram and a section |
415 |
|
which talks about the issue but finding them will take time. |
416 |
|
|
417 |
|
The distinct pieces (Javadoc and the |
418 |
|
design documentation) cannot seen as a whole. |
419 |
|
|
420 |
The obvious question, then, is: can we increase the overall value by hyperlinking the |
The obvious question, then, is: can we increase the overall value by hyperlinking the |
421 |
two distinct pieces of documentation? |
two distinct pieces of documentation? |