Every computer science student has taken a course that requires them to make charts, diagrams, graphs and other visual tools. One of the biggest tools I wish I knew about early on is plantuml in markdown files.

Unified modeling language, the UML portion of plantuml is as a visual modeling language. To be more specific, plantuml is just a good open-source tool that incorporates uml and other things like support for visualization of JSON and YAML files.

Markdown (a .md file) is a language that lets you format text and symbols. 

The combination of these languages would have made many of the courses in my past much easier. I could also see it being useful in the future when it comes to modeling any work. VScode only requires a couple extensions to get it to work .

There are a few different sources one could go to, to figure out how to write the code that they need for whatever task is at hand. Those resources will be listed at the end.

For now there will be a couple basic examples showing how the diagrams from the previous blogs are made.

This is the diagram from the previous blog:

For this breakdown we will be keeping it simpler and using a smaller portion of this diagram.

The diagram we will be looking at:

Oh how nice it would have been if I could use this to organize group projects early on in my academic career. 

the code to make it present this way looks like this:

With the plantuml extensions you simply put 3 back quotes (“`) and plantuml. Then go to town following whatever cheat sheet you like to use to help you write the code. You can show relations, display classes and even put notes for more details.

This example keeps it fairly simple, it can get a little more complex depending on the size of your diagram and what you are doing. 

Like was mentioned earlier you can even make diagrams for relational databases!

ex.)

The amount of time me and my friendsin class had spent using different cookie cutter diagram makers in our browser that would hide features we needed behind paywalls…

Even if you’re just making a list of tasks you need to do or formatting a paper markdown by itself has a lot of useful tools. One of my personal favorites is crossing off a list using the tilde key (~).

ex.)

Markdown and plantuml are on the same list as unit testing when it comes to things I wish were taught before getting deep into programming courses. 

Do yourself a big favor and get at least a little familiar with it.

Cheat sheets:

Plantuml simple – https://ogom.github.io/draw_uml/plantuml/

Plantuml official – https://pdf.plantuml.net/PlantUML_Language_Reference_Guide_en.pdf

Markdown simple – https://github.com/adam-p/markdown-here/wiki/markdown-cheatsheet

Markdown official – https://www.markdownguide.org/cheat-sheet/

Sources: 

Database example – https://medium.com/@elvis.gosselin/plantuml-for-database-modeling-1b71e6d4622d

From the blog Mikes CS 343 by Michael St. Germain and used with permission of the author. All other rights reserved by the author.

Along with class diagrams is the topic of a sequence diagram (mentioned in previous blogs). Sequence diagrams are a good way to understand the flow of a program that helps developers when it comes to creating and testing their products.

This blog will go into detail of how to read a sequence diagram and show why they are important.

To start here is the example given from a class activity and the previous blog:

As an overview this is the sequence diagram for a program that creates a student and a day. Courses and appointments are assigned to a student, working as a mock schedule creator. The student has a name, phone number and an email address. Days are a collection of courses and events. The courses have a start time, end time, course code and room number. The appointments have a start time, end time and description. Displaying the day shows all of the assigned courses and events.

With the overview we can look into how all of that information is extracted using just the sequence diagram. Ideally you would want a class diagram as well in order to write the program initially but the sequence diagram also helps explain the flow and give an idea of what should be tested.

Starting from the top we have a user, that being the driver class that someone is using to run the program. We begin with creating 2 days and two courses. The courses variables are listed above the line leading to the order of their creation. Next a student is created. This student is named sam and the associated variables are listed in a similar manner. An appointment is created in a similar manner as the courses.

All of the created courses and events are then added to the list of events. A new course is created and added to the events. Then comes the “testing” portion. By displaying the days you should get outputs that show all of the events. After removing the created appointment and displaying the day again you should see it has been removed.

All of this shows the actual behavior a program should have. Along with giving samples of inputs that can be used to test that the program is working as intended.

Below is the code written to match the sequence diagram:

As one can most likely see. The code itself follows the diagram almost perfectly. The main differences are just the syntax and the way certain aspects are implemented. It’s important to check over the class diagram and code itself to know how to properly implement the sequence diagram.

The power of a sequence diagram is that it gives a developer a basic example of a program’s expected behaviors. For actual proper testing you would want to implement more things that wont be discussed here. However it is a strong stepping stone leading towards that.

From the blog Mikes CS 343 by Michael St. Germain and used with permission of the author. All other rights reserved by the author.

For teams of developers having a centralized repository for code is essential. Git provides an extremely powerful and relatively user-friendly base for teams to collaborate effectively.

After teaching one of my close friends, involved in a development project at work, the basics of class diagrams. They gave her a more hands-on role with the entire development process. Even though she had never worked with programming before, having someone in a business oriented role who could communicate and check over the team of developers was perfect for them.

That’s when she was selected as the product owner for her company’s new website. In a serendipitous twist they were using git as their repository while I simultaneously was being taught about it in school.

The next step was to teach her a basic overview of how it all looks from a developers perspective.

We started with a picture from my professor.

At first glance, I had completely lost her. After explaining that she wasn’t the maintainer responsible for handling all of this her mind was eased a little. The main ideas were just to understand the flow of how the developers were going to be working. All she had to remember was FCBPP.

This acronym I created for her was simple. They would FORK their own copies. Make CLONES of that. Make a BRANCH where they would do their work. PUSH that work kind of like a save. Then create a PULL request. As a developer it is obviously a lot more nuanced and there are more steps involved. But for someone that isn’t actually doing hands on work that was enough.

After getting the gist of it and before getting further into the details of how it would benefit her to know that stuff. We took a look at the stuff she would really be involved with. The product and sprint backlogs.

In git it is actually fairly easy for someone who doesn’t really understand programming itself to look at, arrange and audit backlog items. It would also allow her to check in regularly to see where the team was when her boss would ask questions.

In the real life case while explaining this part we did use the real github of her company but for the sake of confidentiality it will be a new blank project.

I told her to focus on the issue board under planning. It looked similar to this:

With properly labeled boxes and the lists of items and features the team was working on or planned to work on she felt so much more comfortable asking about things and helping plan everything out. After circling around the topic a few more times we realized just how powerful having a product owner who knows this process could be

We also joked with her boss that with me teaching her these things I should be hired as a consultant (small business unfortunately) with a bonus for my professor.

From the blog Mikes CS 348 by Michael St. Germain and used with permission of the author. All other rights reserved by the author.

Writing good clean code is a work of art that takes a lot of practice and understanding. One of the first practices you should use is what’s called design smells. Design smells are indicators of possible poor design principles that will eventually impact the quality of your project.

We’ve all had that point when we first started learning how to write code where we wrote some pretty ugly “spaghetti”  code. To start, the names of these smells are rigidity, fragility, immobility, viscosity, needless complexity, needless repetition and opacity. Most of these tend to go hand in hand or could stand alone. 

It’s good to know their meanings before talking about their importance.

Rigidity: when your software is difficult to change in even the simplest ways. 

Fragility: having a tendency for your program to break in other places when you make a change.

Immobility: having useful code that could be used in other systems, but can’t be integrated very easily

Viscosity: when it’s not easy to make only one change.

Needless complexity: containing things that don’t really have any use yet.

Needless repetition: repeated code that could be abstracted instead or written over and over.

Opacity: not visually clear.

While the use of being able to identify these design smells may be obvious to some. We will start with some examples before ending with why identifying these smells will be helpful in the long run.

When first starting a project sometimes it’s hard to know where to really start. That is why developers have tools such as class diagrams, but that is for another blog. Starting off with no real design in mind it’s easy to have needless repetition pop up. Once you’ve identified you can break certain things off and turn them into their own methods, you may also realize it has caused rigidity and fragility. Moving those lines might be much harder than you think. Those problems also lead into viscosity if you end up with a big enough mess (speaking from experience).

Next is the problem of needless complexity. Without having a class diagram you might find yourself jumping ahead to try and fix a problem or do something you don’t have a need for yet. The problem is exacerbated if you don’t end up needing it at all. No one likes useless code. This can lead to opacity when your code is making the goals and intents of your work unclear.

With the previously discussed class diagrams (see previous blog) to guide you. Along with an understanding of poor design principles it’s easy to see how being able to identify these smells can keep your work in much better shape for yourself and others. We have stuck with the design process for now, a future blog topic will cover how to make the code itself “cleaner”.

From the blog Mikes CS 343 by Michael St. Germain and used with permission of the author. All other rights reserved by the author.

In part 1 we covered the different types of software licensing and how they work. Now we will be looking at why you should pick a license, how you should pick a license and which license you should pick from the plethora of options.

We will start with why you should license your software. In reality there are many reasons why you would want to put a copyright and license on your software. It is something that you created after all. It is your intellectual property and hard work. You wouldn’t want someone to steal it and use it for their own gain with no credits or regards to you. You also wouldn’t want to be found liable if someone uses what you wrote and it causes something bad to happen whether it be system breaking or cause a security breach.

As for how you license your software. There is a massive amount of licenses to choose from and you don’t need to make one from scratch. In fact it is very much recommended to use one of the many that have already been created and are easy enough to add on to what you’re working on. Leave it to the legal professionals and save yourself the time and effort.

Which license is best for you depends on your own beliefs and what you would want others to be able to do with your work. As stated in part one a closed-source project is likely something you’re doing in a commercial setting so unless you’re the business owner it won’t be your decision.

If you’re starting your own project and aiming for it to be open source and don’t care too much if its modified and has the license changed or is incorporated into an existing project under a closed-source project a permissive license will be fine. You’re still the owner and your own code is still open source. An MIT license would work for you

If you’re like me and don’t want your work to be used in a setting you don’t have insight to or the ability to decide which license is used, you may look to copyleft. A GNU General Public License would be good in this case.  

There is somewhat of a middle ground however.

Mozilla is a special case and has their own license called Mozilla Public License (MPL). It is considered a weaker copy left since it does allow developers to use their software inside of a project with a different license . Though  still requiring the portions used under their license remain under their license and be open source instead of the whole project. In my opinion, it seems to be a great blend for the future of FOSS and would be my choice.

From the blog Mikes CS 348 by Michael St. Germain and used with permission of the author. All other rights reserved by the author.

Software licensing has quickly become one of my favorite topics to research. When I was first introduced to the topic I sarcastically thought and said “yay” imagining the legal nonsense that i thought was coming. My professor told me he actually found it very interesting and it shouldn’t really shock me that he was right.

There are different categories for the different kinds of licenses that serve different purposes. 

You have the closed-source license which everyone is familiar with. This would include things like operating systems, Microsoft windows or Apples ios. Unless you’re a maniac using Linux on your personal computer. It also extends to a lot of smaller more commercial products like zoom, adobe products and a good amount of video games.

On the other hand you have open-source software that is steadily becoming more and more popular. You have my preferred web browser (Mozilla Firefox), the previously mentioned Linux and WordPress (where this blog is being written).

While closed-source software has a very strong and sometimes important foothold in the world we live in. There are many developers who strongly believe in the continued growth of free open source software (FOSS). For personal reasons my independent research and guided learning have pushed me towards those beliefs as well.

Inside of open-source software there are different types of licensing which can be categorized as copyleft and permissive. Both of them are great if you believe in FOSS but they do have some interesting aspects that make them different.

To start, a permissive license does exactly what you would imagine for open source software. It lets users use, modify and distribute it with minor restrictions. An example of this would be an MIT license which is used by jQuery and node, which are libraries and runtime environments for JavaScript. The minor restrictions of an MIT license are fairly basic. There’s no warranties, no liability, you must retain the copyright notices and accept liability for any issues caused by using the software.

In contrast, a copyleft (or restrictive) license has all of these restrictions but it gets to be interesting when you also restrict changing the licenses down the road. Basically with a copyleft license it forces anyone who uses, modifies and distributes the software to use the same license. This removes the ability of a user to lock up and sell their version of the software. The one drawback is you cannot use a copyleft licensed work inside of a project that uses a different license. An example of copyleft licensed software is the Mozilla Firefox web browser.

you may be thinking how do i pick a license? which license is best? which license is for me?

These questions will be answered as we explore more in part 2!

From the blog Mikes CS 348 by Michael St. Germain and used with permission of the author. All other rights reserved by the author.