[2020/02/22] - So I find that software development gets somewhat difficult when you are modelling an actual system for systems integration. What appears to be a simple piece of software, suddenly becomes difficult. So I'm looking for tools to model processes and classes and decided that modifying an SDLC process makes sense. However, UML tools are somewhat expensive and have binary/proprietary save files which makes them difficult to use for version control. I have found that taking notes doesn't really work so well.
I'm not really an expert on UML, so this document is going to be really me trying to figure out a process to document and model the processes I work on and integrating it into a software development process. I will be adding more pages with examples, as I do them, as well as explain them here with relevant PlantUML code.
Mazanec and Macek [4] describe the strengths and weaknesses of using PlantUML. As a text markup language (TML), it produces graph is programmatically so it is clear what the diagram is describing, which might be a problem with visual tools which are used incorrectly. However, it may be somewhat difficult to produce these graphs as in-depth tutorials into the UML language are generally visual and do not have PlantUML code in it. As a results, I'm probably going to bite a lot of prose and digrams while temporaily building this diagram. However, all images are linked to their original sources although it might be missing property citations. This is currently a work in progress for me.
From a visual perspective, the integration of PlantUML into Sphinx allows the PlantUML code to be embedded into code documentation, which places the diagram under source control. However, for presentations the automatic placement of the graphs may not be of the greatest of quality to an export chain to an editor of choice maybe necessary. In my case, I find that it maybe necessary to do PlantUML -> LucidCharts -> Visio for more aethestically please graphs.
I have found this process for code development helps in organizing my work. Although there appears to be a move to functional programming, which is essentially leaving modelling to activity charts. I find that functional programming becomes more difficult as the application scales. Functions end up taking extremely large argument lists and returning large arrays and dictionaries. Working within a modelling environment allows me to appropriately design portions of the application based upon reusable pieces.
Generally, if we have a project directory, I will generally start with
./myproject
src/
myproject/
mymodule1.py
doc/
tests/
integration/
<feature_name>
<feature_name>_reference/
unit/
mymodule1/
MyModule1Class1/
resources/
doc/
mymodule1class1.py
dev_MyModule1Class1.py
test_MyModule1Class1.py
In early development attempts, I initially had a dev/directory for developing new features. I find that this approach ends up being problematic because it puts the development code and the testing code in different directories. When a piece of functionality is created on dev, then it becomes possible to determine if a piece of code is working, before hand. Additionally, this approach allows me to created documentation artifacts within the /test directory for documentation. Ideally, we would like this to be in an autogenerated doc folder.
Larger pieces of functionality can be created in the integration directory. The reference implementation provides a mechanism for regression testing to ensure that the software produces the same results as the reference.
mymodule1class1.py
allows me to "monkey patch" new features, test features with the monkey patch before commiting it to src/myproject/mymodule1.py
. For purposes of testing, it maybe necessary to stub out methods in the monkey patch if we want the code to be used in continuous integration testing. However, I have just currently gotten started on learning to do continuous integration [2/24/2020] in a scientific type environment.
import myproject.mymodule1.MyMoudle1Class1
class MyModule1Class1(myproject.mymodule1.MyMoudle1Class1): pass
The Unified Modeling Language (UML) was created to forge a common, semantically and syntactically rich visual modeling language for the architecture, design, and implementation of complex software systems both structurally and behaviorally.[1] I will fill out this page with example for PlantUML. I will likely use example flowcharts from the internet to replicate, and copy/paste some prose, until I have some time to flesh it out with Materials Science Examples.
The UML specification divides modeling into a variety of activities, which can be classified either by modeling of the data structures, or the modeling of the process. Structural diagrams attempt to capture the underlying data models. Process diagrams visualize, specify, construct, and document the dynamic aspects of a system.
[Simpifying UML]
“UML specification is a huge book (732 pages), the UML metamodel is large and quite complex, and the definition and the understanding of its static and dynamic semantics is a truly difficult task, with also the consequence to make difficult to teach it both at the school/university level or in the industry (Grossman et al., 2005).”[from Reggio2014]
"“Seriously, you need about 20% of the UML to do 80% of the kind of design you might want to do in a project – agile or not – but use the UML with a very light touch: use the notation to reason about a system, to communicate your intent to others…and then throw away most of your diagrams.” – Grady Booch [from Cabot2018]
Since the people who will be primarily designing and writing these diagrams are not professional business analysts, the UML training for them should be abbreviated. To determine the most important diagrams to focus on, we should look at those diagrams, which are most often used in software development. A survey done by Reggio et al [4] indicates that four structural diagram (object, class, and component,For structural diagrams, the four most used diagrams are the object diagram, class diagram, and the component diagram.[Gallia] These are the ones should be done first. For behaviorial diagrams, the use case diagram, sequence, and activity diagrams are the most important. [Gallia]
Structural UML diagrams
Behavioral UML diagrams
[Booch1994] Grady Booch, Jim Rumbauch, and Ivar Jacobson,
[Reggio2014] Gianna Reggio, Maurizio Leotta, Filippo Ricca, Diego Clerissi. "What Are the Used Activity Diagram Constructs? A Survey" . Proceedings of the 2nd International Conference on Model-Driven Engineering and Software Development - Volume 1: MODELSWARD, 87-98, 2014, Lisbon, Portugal. [Link]
[Cabot2018] "What do their creators think about UML now?" Feburary 5, 2018. Modeling Languages. https://modeling-languages.com/uml-opinions-creators/ [Acessed 2/24/2020]
[1] LucidChart. "What is Unified Modeling Language[sic]" Link
[2] Agile Modeling. "Introduction to the Diagrams of UML 2.X " Link
[3] Scott W. Amber. The Object Primer 3rd Edition: Agile Modeling Driven Development with UML 2. Cambridge University Press 2004.
[4] Gianna Reggio, Maurizio Leotta, Filippo Ricca, Diego Clerissi "What are the used UML diagrams? A Preliminary Survey" Link
This is a text-based model. I'm thinking about adopting it, even though it doesn't provide pretty diagrams. However, I can put the diagrams under version control. As a result, we will use the PlantUML language to describe processes.
PlantUML does a "pretty good" job of laying out diagrams in an agile manner - I can generate them quickly without having to worry about layout being perfect. However, once I start to have a "stable" diagram, I'd like to present a cleaned up version. Unfortunately, PlantUML won't let you fine-tune some of the details to get to that step. But I know I could do it in Visio. LucidCharts also has the ability to read PlantUML files and convert them into a file format so you can "prettify" the final document.
For OSX.
1. PlantUML extension by jebbs
2. Run the following commands
brew cask install java
brew install graphviz
3. Add the following lines in the .vscode/settings.json
"plantuml.diagramsRoot": "docs/diagrams/src",
"plantuml.exportOutDir": "docs/diagrams/out"
For Windows.
1. PlantUML extension by jebbs
2. Open an administrator prompt with administrative privileges. You can use that to launch Command Prompt with admin privileges. Press Windows+R to open the “Run” box. Type “cmd” into the box and then press Ctrl+Shift+Enter to run the command as an administrator.[1]
3. Run the following commands.
@"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"
choco install plantuml
4. Add the following lines in the .vscode/settings.json
"plantuml.diagramsRoot": "docs/diagrams/src",
"plantuml.exportOutDir": "docs/diagrams/out"
[1] Microsoft Corp. PlantUML. Link
[2] Walter Glenn. "How to Open the Command Prompt as Administrator in Windows 8 or 10"
[3]Ashley Engelund. "Ashley's PlantUML Documentation"
[4] http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.661.5380&rep=rep1&type=pdf#page=9