Documenting via mapping into patterns

It's always desired to have well-documented code. Sometimes it is perfectly enough to have just meaningful names in the code (for classes, methods, etc.). Sometimes we need a comprehensive documents and diverse diagrams. The degree of document covering depends on different factors including external (e.g. customer's wish), internal (frequent movements of people in a team) or both. Choosing the appropriate level of documenting for project is out of the scope of this article. Here I'll explore one method of documenting that can fit for you.

Problem

Let's assume the following:

• the system under development is large and has a lot of functionality

• the architecture is well-defined and implementing one use-case doesn't need a lot of challenge

• the project team is large and developers are not very skilled, since implementing isn't very difficult process

The objectives:

• each code of particular functionality must be documented with diagram with at least class granularity

• each developer should be able to document his implementation of a use-case

• the amount of time on documenting and learning UML (developers are not very skilled and haven't strong knowledge of UML) should be minimized

Solution

The basic steps of the solution are:

architect

1. defines architecture patterns that are used in implementations
2. develops diagrams of typical pattern frameworks
3. defines for each pattern framework artifacts that are involved

developer

1. chooses appropriate pattern framework for particular use-case (this step is the most critical and sometimes need for approval from senior)
2. maps his solution, his code artifacts (classes, interfaces, etc.) to the pattern framework artifacts
3. develops a diagram of his implementation based on pattern framework for better visualizing a mapping between both of them

Architecture patterns and pattern frameworks should be defined more precisely and in more comprehensive manner, while outcome from developers can be more lightweight (even the last step can be omitted)
 

Example

The example is based on well-known J2EE patterns. They are well-documented, so they fit perfectly (as I mentioned that architecture patterns used in software system should be described by an architect).

Here is an example of a diagram of the pattern framework that developer is going to use in implementation of particular use-case:



And here are the documentation artifacts, which are produced by developer:

Mapping

AccountController –> Front Controller

CreateAccount panel, header, footer –> Composite View

AccountView, UserLogonInfo –> View Helper

AccountDelegate –> Business Delegate

AccountServiceLocator –> Service Locator

AccountService –> Session Facade

AccountVO –> Value Object

AccountDaoData –> Access Object

Diagram