Consistent architecture diagrams for C++ projects
Marius Feilhauer About me
￮ M.Sc. Automotive Engineering @ University Stuttgart ￮ PhD thesis Simulation-based validation of advanced driver assistance systems @ HLRS University Stuttgart (Prof. Resch) and ETAS GmbH ￮ Working experience @ Robert Bosch GmbH, Aston Martin Ltd. and Porsche AG ￮ Software developer of C++ based simulation models @ ETAS GmbH ￮ Lectures @ University Stuttgart
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 2 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Introduction and Overview
Source Code
Test
Repository Build Tooling Download Server Build Scripts v1.0 v1.0 v1.1 v1.1 v1.2 v1.2 v2.0 v2.0 Documentation ?
Diagrams
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 3 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Agenda
￮ Good documentation
￮ Architecture and code visualization
￮ Consistency
￮ Diagrams as code
￮ Takeaways & Outlook
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 4 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Good Documentation
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 5 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Golden nuggets Guiding principles by atlassian
Keep it brief Visuals are key Know your audience
www.atlassian.com/software/confluence/documentation
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 6 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Documentation use cases Two examples Mh, Cool new undocumented library functions
I get this issue ah, we changed unprofessional this …
Adam Scott, www.oreilly.com/ideas/the-eight-rules-of-good-documentation
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 7 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. The eight rules of good documentation
1. Write documentation that is inviting and clear 2. Write documentation that is comprehensive, detailing all aspects of the project 3. Write documentation that is skimmable 4. Write documentation that offers examples of how to use the software 5. Write documentation that has repetition, when useful 6. Write documentation that is up-to-date 7. Write documentation that is easy to contribute to 8. Write documentation that is easy to find
Adam Scott, www.oreilly.com/ideas/the-eight-rules-of-good-documentation
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 8 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Fast understanding Professional Enforces to express of your intentions public image intentions precisely
Additional benefits when using consistent diagrams within your documentation
www.atlassian.com/software/confluence/documentation
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 9 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Diagrams and code visualization
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 10 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. UML Diagrams UML Diagram Overview
Structure Diagram Behavior Diagram
Class Diagram Use Case Diagram
Object Diagram Activity Diagram
Package Diagram State Machine Diagram
Composite Structure Diagram Interaction Diagram
Component Diagram Sequence Diagram
Deployment Diagram Communication Diagram
Timing Diagram Profile Diagram Interaction Overview Diagram
based on www.uml-diagrams.org/uml-25-diagrams.html
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 11 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Grade System Example Use Case Diagram
Madeline Adair, Use Case Diagrams, www.slideplayer.com/slide/677748
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 12 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Shopping Example UML Component Diagram Example
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 13 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Abstract Factory Design Pattern UML Class Diagram Example
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 14 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Let’s get a coffee Activity Diagram Want some coffee
Walk to the coffee machine
Brew coffee
want milk Add milk don’t like milk
Take coffee
want some sugar Add sugar no sugar for me
Enjoy coffee
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 15 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Smart Home Example Deployment Diagram
deployment Smart Home
:PC :Tablet :Smartphone
:Web Browser :Web Browser :Web Browser
:Serv er
:Web Service :IoT Controller
«Sensor» «Sensor» «Sensor» «Sensor» :Temperature :Light :Contact :Humidity
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 16 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Diagrams allow to transport information easily and there are many different options available how to draw them
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 17 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Consistency
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 18 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Consistency
Documentation Documentation v1.0 v1.1
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 19 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Draw diagrams by using code Source code of diagrams has to be kept in-sync with the rest of the code and its documentations
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 20 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Diagrams as code
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 21 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Overview Diagrams as code
￮ Available tools allow automated generation of diagrams Doxygen, CMake, PlantUML
￮ Easy integration into existing build toolchains
￮ Automatic approaches vs. scripted diagrams
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 22 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Example project Directory structure
Example
Vehicle
Traffic Light
Vehicle Garage
Vehicle Creator
Race Game
CMake
Documentation DependencyGraph
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 23 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Example project CMake targets
Executable Executable Race Game Vehicle Creator
Dynamic Library Static Library Traffic Light Vehicle Garage
Dynamic Library Vehicle
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 24 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Dependency Graphs Cmake & Graphviz
CMakeList.txt Graph.dot Diagram CMake Graphviz
Build Tooling
https://www.graphviz.org/
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 25 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Dependency Graphs Cmake & Graphviz
add_custom_target(DependencyGraph COMMAND cmake --graphviz=DependencyGraph.dot . COMMAND dot -Tsvg DependencyGraph.dot -o DependencyGraph.svg WORKING_DIRECTORY ${CMAKE_BINARY_DIR}) CMakeLists.txt
CMake Live Demo
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 26 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Collaboration Diagrams Doxygen
COLLABORATION_GRAPH = YES doxyfile
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 27 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Include Graphs Doxygen
INCLUDE_GRAPH = YES INCLUDED_BY_GRAPH = YES doxyfile
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 28 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. UML Diagrams PlantUML
Diagram.plantuml Diagram PlantUML
Build Tooling
www.plantuml.com
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 29 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. PlantUML Some Examples
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 30 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. PlantUML Live Demo in Visual Studio Code
&
Visual Studio Code PlantUML Extension
PlantUML Live Demo
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 31 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. PlantUML Doxygen & Markdown Integration
# This is a vehicle model
This example shows a PlantUML diagram within a Markdown file to be processed by doxygen.
@startuml "Vehicle Simulation"
start :Create Vehicle; repeat :Query position; repeat while (stop simulation?) stop
@enduml
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 32 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. PlantUML Consistency
DiagramA.plantuml DiagramA
Classes.iuml
DiagramB.plantuml DiagramB PlantUML
Style.iuml
DiagramC.plantuml DiagramC
Doxygen & PlantUML consistency demo
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 33 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Great tooling for drawing diagrams as code is already available! and it even integrates nicely with CMake and Doxygen
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 34 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Takeaways & Outlook
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 35 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Takeaways & Outlook
Visuals are key Diagrams as code
Great tooling available Single source Fun & easy & version controlled to work with
￮ Doxygen name resolution ￮ Reference of header files Doxygen link demo
Public | Dr. Marius C. Feilhauer - ETAS/ETS-Fe | 2019-11-15 36 © ETAS GmbH 2019. All rights reserved, also regarding any disposal, exploitation, reproduction, editing, distribution, as wel l as in the event of applications for industrial property rights. Thank you