11

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:

enter image description here

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.

  • um UML and some plain old text usually – jk. Apr 25 '17 at 10:39
  • If you can read German, take a look at arc42.de/template/index.html They show some guide lines for documenting software architecture. – Bernhard Hiller Apr 25 '17 at 11:03
  • 8
    "Not bothering to do it at all" is probably the closest to a standard. – whatsisname Apr 25 '17 at 16:15
13

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)
| improve this answer | |
  • This is a very good approach, thanks. Stepping back, one could think it is pretty much obvious, but it helps a lot to disconnect the various 4+1 pieces I all had on one graph. – WoJ Apr 25 '17 at 16:59
5

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.

| improve this answer | |
  • Package diagrams? Deployment diagrams? Component diagrams? – Nick Keighley Apr 27 '17 at 12:34
  • 3
    Honestly a bunch of boxes with arrows can work wonders for communicating a number of design features. I guess the component diagrams fall in to that category, but my clients understand data flow with boxes representing the main bits. I agree with Doc Brown. The formality of UML misses the mark with it's intended purpose. – Berin Loritsch Apr 27 '17 at 13:48
  • @NickKeighley: see my edit. – Doc Brown Apr 27 '17 at 14:06
  • @BerinLoritsch: IMHO "a bunch of boxes with arrows" characterizes the diagram types mentioned by Nick Keighley. Data flow diagrams, however, make a clear formal distinction between data or groups/clusters of data, and processes or components which transfer or transform these data. That is nothing I can express with any of the UML diagrams easily. – Doc Brown Apr 27 '17 at 14:11
  • 1
    I have to admit I sometimes resort to Data Flow diagrams - particularly the ones that allow stores. In fact the top level diagram that describes our system is essentially a DFD. I do still find Class diagrams and Package useful to some extent. I don't pay much attention of the "formal" parts of UML. – Nick Keighley Apr 27 '17 at 14:36
0

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.

| improve this answer | |
  • The formal specification can be found at omg.org/spec/UML/2.5 but there are plenty of friendlier tutorials on the web. – Simon B Apr 25 '17 at 11:24
  • 2
    This answer only a part of the question, UML is deifnitively the right tool to modelise, but this does not constitute a full documentation by itself – Walfrat Apr 25 '17 at 11:24
  • 3
    Does anybody use UML very often? – Panzercrisis Apr 25 '17 at 13:01
  • doodling. reverse engineering. – Nick Keighley Apr 25 '17 at 13:03
  • 1
    @Walfrat. is it? Really? I have my doubts. – Doc Brown Apr 25 '17 at 18:55
-3

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.

| improve this answer | |
  • 3
    does not answer the question, probably better as a comment on SuperGirl's answer. – Newtopian Apr 25 '17 at 12:55
  • 1
    It addresses the question. I'm arguing that the answer to the question is more "No" than it used to be. – Nick Keighley Apr 25 '17 at 13:46

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.