Software Design

[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.

What has worked for me

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

Plant UML

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.

Installing the PlantUML extension by jebbs

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"

References

[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"

• https://www.youtube.com/watch?v=xkwJ9GwgZJU z

[4] http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.661.5380&rep=rep1&type=pdf#page=9