Embedded Diagrams on Source Code
Contents
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:
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.
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.
@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.
@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!
