[Zero To Python] Day 3 - Design With Paper
[Zero To Python] Day 3 - Design With Paper
It always starts with paper
Today we are going to start designing the journaling program. You might think that this is going to involve whiteboarding or fancy software design diagrams.
Nope. Today we use paper!
I’ve found that designing software on paper first is the best approach. Paper and pencil is still the best medium to get ideas “on the page” while still being able to cheaply make changes. Also, paper is less intimidating. It doesn’t feel final or perfect. It’s just words and boxes on a page. If you don’t like it, throw it away and do it again!
So, paper wins for design.
A Few Design Requirements
Let’s think about the program requirements before we dig into the design. Here are some bullet points of what this Journal program is going to be:
text based system
runs on the command line
typed commands like `journal help` to view help, etc.
each screen is a specific command
no command loop/single command per run
commands like new, list, view, edit, delete, help…
plain text journal files (human readable)
As you will see in my design, the journal program we are building is influenced by the requirements above. If this were a mobile app or web based system, the design would be different.
The important part of program design is to understand the requirements up front and do your best to build the appropriate software based on the requirements. And if you are the person coming up with the requirements, you will probably find yourself asking and answering questions like “how would I do this?” or “how should this feature work?”
Notes On My Design
Let’s walk through my design, screen by screen.
Default Screen
If the user runs python3 journal.py they get what I’m calling the default screen. It looks like this:
The idea here is to show the user the name of the program, the version number, and a list of useful commands. This gives our user a good jumping off point to use the journal program. This is a fairly common pattern in command line programs.
Already you can see this exposes our program functionality. It implies six commands - help, new, list, view, edit, and delete. That means we need to go design those screens. This is where you start to see the design process of even a single screen shaping the rest of the program.
Help Screen
If the user runs python3 journal.py help they will get the help screen. It looks like this:
The help screen is a more in depth version of the default screen. It provides a longer description of the journal program than the default screen. It’s possible in future versions there could be a more in-depth help screen per command. We aren’t starting there, but the design starts to unmask possible features as we go.
New Screen
If the user runs python3 journal.py new they will get the new screen. It looks like this:
The new screen is where the user can create a new journal entry. Based on the design it’s possible the date could be auto populated to the current date. Or maybe the user types in the date. I could see either option being useful. Journal entry text looks like free form plain text, which is what we want.
This is where the data structure for our journal entry starts to make sense. It looks like a journal entry has a date and some text. That will become useful later when we figure out how to store and represent journal entries in our program.
List Screen
If the user runs python3 journal.py list they will get the list screen. It looks like this:
The list screen is where the user can see a list of journal entries. Each entry is displayed as the date and a short text blurb from the journal entry. It’s not clear yet how much text should be displayed for each journal entry. That requires experimentation once we build the screen and have real journal entries to work with.
View Screen
If the user runs python3 journal.py view <date> they will get the view screen. It looks like this:
The view screen shows the user an individual journal entry. One interesting bit for this command is that the user inputs the date as part of the command input. That is what the <date> represents and you can see that in the design. We will be reusing that pattern for the edit and delete screens.
This also adds some constraints to our program. Each day can only have one journal entry. We will do lookup based on the date. That impacts the code you will get to write later in this course.
Edit Screen
If the user runs python3 journal.py edit <date> they will get the edit screen. It looks like this:
At first glance the edit screen looks like the view screen. There is one key difference. On the edit screen the user will be updating the journal entry for a particular day with new content. The design treats this as a full replacement of the journal entry, not editing particular parts of the text.
Delete Screen
If the user runs python3 journal.py delete <date> they will get the delete screen. It looks like this:
The delete screen functions as a confirmation. The user is asked if they wish to delete a journal entry. If they type y they agree and the entry is deleted. If they type n it’s not.
This is a confirmation and not automatic deletion because people make mistakes or type in the wrong input. It’s good to give the user the opportunity to confirm their choice before deleting their data.
Assignment
Your assignment today is to draw out your own program design using a pencil and paper. We will be using my designs as a basis for the journal program we are building. However, this is a good opportunity for you to practice software design and come up with your own ideas and features. Program design is fun and it is one of the most creative parts of programming.
Keep it fun and remember… anything is possible on paper!
You’ve Now Designed Your First Program
Congratulations, you’ve now walked through the process of designing a software program. At a basic level all software design goes through a similar process. You will find this experience useful throughout your adventures as a programmer.
Tomorrow, we start to make this design reality, so see you then.
-Brian