Is there a standard for documenting a program's high-level architecture?

Question

I am an amateur developer and all my programs up to now were simple enough to be documented within the code. While reading the code it was clear what I was doing such and such action (my standard test was to look at the code 6 months later and understand everything at first read - and I have short memory span).

I am now faced with a program which is outgrowing my capacities to remember the various interactions between

• the code itself
• the indexes in the database
• the interactions between various modules ("worker" core code and "library" ones)

My current documentation is a whiteboard where I have all kind of boxes and arrows which point to code, to database indexes, to actions being executed, to state change etc. Just for reference, a fragment of the mess:

My question is whether there is a standard, or named set of best practices (named in the sense that this is a set of practices which were grouped under a specific name) for the documentation of more complex products.

What are the keywords I should look for (general attempts at "document software architecture standards" and similar variations usually led to software for workflows or building architecture CAD systems).

I also expect that there may be no general best practices for high-level descriptions and that everyone builds its own philosophy.

Answer 1

There isn't one standard that everyone adheres to. Software projects can vary greatly (think: helloworld.py vs the code in the space shuttle).

One very common method is to use the 4+1 model. Instead of trying to cram everything into a single style of document, this methodology breaks the design into five components:

• The Development view
• The Logical view
• The Physical view
• The Process view
• Scenarios

The various views describe the product from four different perspectives. The scenarios are where the use cases live, and describe the interaction of the other views.

Note: This is a conceptual model, and is not tied to any specific tool.

You can read more here:

1. 4+1 architectural view model (wikipedia)
2. Architectural Blueprints—The “4+1” View Model of Software Architecture (IEEE paper - pdf)

Answer 2

IMHO UML is not a tool which works well for documenting real world software's architecture. Class diagrams are useful, but use a level of abstraction which is often too low for this purpose. Use case diagrams are typically too "high-level" and miss certain aspects. Other UML diagram types have similar problems (To be fair, package diagrams, deployment diagrams, component diagrams can document certain architectural aspects, but personally I never found them very useful).

If you are looking for a working, pragmatic way of documenting high-level architectures, I suggest to make yourself familiar with data flow diagrams. These are easy to understand and have the advantage they can scale to different levels of abstractions. I have found them most useful to document different kind of systems. Too bad they did not find they way into UML, but nethertheless you find lots of tools - even free ones like Dia or DrawIO - for making these diagrams.

As a side note, why do you require "indexes in the database" in a high-level documentation? I think they are an implementation detail of your (relational?) data model, and if you add them or not is - to my experience - more a question of performance and optimization.

Answer 3

The Unified Modeling Language (UML) is a general-purpose, developmental, modeling language in the field of software engineering, that is intended to provide a standard way to visualize the design of a system.

Answer 4

I think we used to do better. UML seemed to throw the baby out with bath water. In providing a Unified Modelling Language it abolished the distinction between architecture and implementation. Or if it didn't intend to this seemed to be to effect.

I've seen some monster UML models and frankly they don't do anything for me that the code couldn't do, and do it better.