8

I'm working as a support engineer, having access to the source code, and I'd like to use this opportunity to document the source code, but I stumble on a first question: how do I even start?

For single-threaded applications, this is simple: using a tree structure (main() function calls some subfunctions, calling subsubfunctions, ...) can be done quite straightforwardly using standard UML diagrams.

For multi-threaded applications, this becomes more difficult: I could make a tree structure for the threads, and a tree structure for the function calls, but I'm afraid that the linking between both trees might create a very messy document (while the whole idea of documentation is to clarify).

Is there a standard way to document source code for multithreaded applications?

I had a look at UML Diagrams of Multi-Threaded Applications but I don't like sequence diagrams for elaborating subfunctions, calling subsubfunctions, ...

Dominique
  • 1,705
  • 2
  • 14
  • 24
  • 4
    What do you mean exactly by documenting the code? There's no such thing as a standard way to document any code. It depends on the goals of the documentation and the internal organization rules. – kraskevich Oct 31 '18 at 10:50
  • 1
    What language is the code written in? C# XML documenting is built in in Visual Studio and there are several free programs that can generate some nice documentation from those comments. It's a start. – Phil N DeBlanc Oct 31 '18 at 11:39

1 Answers1

5

I'd suggest to use UML activity diagram to show the big picture of the multithreading logic, identifying the building blocks (activities) that may happen independently in each thread, as well as synchronisation activities.

In activity diagrams:

  • joins and forks allow to represent elementary synchronisation between threads.
  • Swimmlanes can be used to highlight separate threads in the visualisation.
  • Within each thread you can show sequentiality, making no assumption about the relative ordering accross two threads.
  • You may also use a joins and forks combined to represent synchronisation possibilites such as mutexes or atomic accesses, which allow to create some constraints about ordering of operations across the threads.

You can then document the different activities in a treewise fashion like you use to do. In addition you can comment synchronisation activities in the code and refer to the control element in the diagram.

Indeed, you could also show concurrency in a combined fragments with a par operator in a sequence diagram. But I would not recommend it here: this will not help to grasp the multithreading much better and doesn't offer any means to show the synchronisation between concurrent activities. These diagrams are more useful for some details on exchange between objects happening in a multithreaded situation than understanding the multithreading logic in itself.

Additional reading:

Christophe
  • 74,672
  • 10
  • 115
  • 187