6 Documenting a Software Architecture （6记录软件架构）.pdf

6 Documenting a Software Architecture 6.1 Introduction Architecture documentation is often a thorny issue in IT projects. It’s common for there to be little or no documentation covering the architec- ture in many projects. Sometimes, if there is some, it’s out-of-date, inap- propriate and basically not very useful. At the other extreme there are projects that have masses of architecture related information captured in various documents and design tools. Some- times this is invaluable, but at times it’s out-of-date, inappropriate and not very useful! Clearly then, experience tells us that documenting architectures is not a simple job. But there are many good reasons why we want to document our architectures, for example: • Others can understand and evaluate the design. This includes any of the application stakeholders, but most commonly other members of the de- sign and development team. • We can understand the design when we return to it after a period of time. • Others in the project team and development organization can learn from the architecture by digesting the thinking behind the design. • We can do analysis on the design, perhaps to assess its likely perform- ance, or to generate standard metrics like coupling and cohesion. Documenting architectures is problematic though, because: • There’s no universally accepted architecture documentation standard. • An architecture can be complex, and documenting it in a comprehensi- ble manner is time consuming and non-trivial. • An architecture has many possible views. Documenting all the poten- tially useful ones is time consuming and expensive. 116 6 Documenting a Software Architecture • An architecture design often evolves as the system is incrementally de- veloped and more insights into the problem domain are gained. Keeping the architecture docum