Embedded Diagrams on Source Code

Why?

• Document the code.
• Include specific information useful when understanding the class responsibilities - functionality.
• Makes future code improvements - bug fixing easier.
• Share design ideas - decisions with other developers.

How?

• Create the diagram source code using PlantUML or similar Framework.
• Paste the diagram in the Header information as note/comment. This can be done in the class definition - header file.

When?

• Given a complex sequence of events that it is important to document (Sequence diagrams).
• Library overview of the architecture (Class Diagrams).
• Software data flow (Flow diagrams).
• Important information for a given class-set of classes (i.e tables).

Frameworks and documentation:

PlantUML online editor

PlantUML documentation

Graphviz online editor

Graphviz documentation

Optional: How to install Visual Studio extensions:

• Go to Visual Studio.
• Select Extensions option in the toolbar at the left.
• Find the extension you are looking for and install it.
• Restart Visual Studio.

Examples:

1- State Diagram: The following example shows the implementation of a state diagram using Visual Studio. The diagram source code is placed in the file header documentation.

State Diagram

Source code:

  @startuml
  [*] --> Idle

  state Idle {
        Idle --> DoSomething : Start Button
  }

  state DoSomething {
        [*] --> SelectItem
        DoSomething --> Idle : Exit Button

        SelectItem --> Pay : ItemSelected
        Pay --> ReleaseProduct : PaymentCompleted
        ReleaseProduct --> SelectItem : ItemReleased

  }
  @enduml

2- Sequence Diagram: The following example shows the implementation of a swim-lane sequence diagram using Visual Studio. The diagram source code is placed in the file header documentation.

Sequence Diagram

@startuml
| Event |
start
|#pink|myComplexClass|

if (needToDoThat?) is (no) then
: ignoreEvent;

|anotherComplexClass|


else (yes)
#lightgray:ExecuteStep1;
:ExecuteStep2;
:ExecuteStep3;
  if (isCompleted?) is (yes) then
  : existComplexClass;
  else (no)
  : getItDone;
  stop
  endif
endif

|#lightblue| simpleClass |

:handleSimpleCall;
:SaveSimpleState;

stop;
@enduml

3- Tables: The following example shows how to embed a table within source code.

Tables

@startuml
:myFeatures table

|= Feature |= Description |= Size |= isAvailable |
| Feature1 | Show information to user | 30 | Yes |
| Feature2 | <#LightBlue> Show App controls to user. | <#LightBlue> 50 | <#LightBlue> Yes |
| Feature3 | <#LightGreen> Alert user when error | <#LightGreen> 25 | <#LightGreen> Yes |
| Feature4 | <#Yellow> Handle user inputs | <#Yellow> 45 | <#Yellow> Yes |
| Feature5 | <#red> Network management | <#red> <color:White>100 | <#red> <color:White>Since v4.0|;
@enduml

Other Uses:

ReadMe documentation for library repositories

Embedded diagrams can be used on ReadMe files to document your library in a graphic way. Any information table, or package UML diagram can be written on PlantUML and added to the readMe file. Then Gitlab or Github will display the actual image (instead of raw diagram code) when your main repository page is displayed.

Just create diagrams you need

When using tools like PlantUML, you can export your diagram as a PNG (or JPG) image file. If you feel comfortable writing diagrams with the tool, go ahead and create your images with it!

Export diagrams