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