Planning a Project - Tic-Tac-Toe
The purpose of this lesson is to learn how to plan out a project before completing it. Until now, we have just been learning through copying code or modifying it and watching the results. While the code will continue to be there to do so with, we are going to start learning about some ways to organize thoughts and go toward a concrete goal - to create a working tic-tac-toe game.
Getting Started
Create the Project
First, we must create the project on GitHub and then clone it to our computer in order to keep our habit of having projects with a history available, and avoid loosing our work or how we got there. You may use any name you would like, however, I recommend something memorable with tic-tac-toe as a part of it, and including a README file when asked.
Prep Some Planning Tools
While I really enjoy using a whiteboard in real life, it is also nice to be able to have versions of what you have planned and updated kept near the code as well diagrams and how they got to where they are. As such, we will be planning our project using Markdown and PlantUML. To use these, we need to do is install the PlantUML extension, in the same way that we did live server. If you want, you may also try the Markdown All in One extension, though it is not required.
To configure it for use, please use File->Preferences->Settings or Cntrl+, then search for "plantuml". You may either use the Java version or configure the server section.
Server
If you are ok sharing data about your project, you can just paste the noted server (https://www.plantuml.com/plantuml) into the configuration area and get going.
Local Setup
To use Local setup, you must make sure that Java and Graphviz are installed, and that the setting is something that can be run. I have the OpenJDK installed on my computer for the Java version, and the path set up to be able to run java from command line, as I develop in it. You may also specify the exact file to run.
Quick Note - Alternative to PlantUML
If you decide that you neither want to use the server version, nor install extra software for the local running, you may use Mermaid instead of PlantUML. It will take less setup, as the Visual Studio Code Extension doesn't require more configuration - however, it does not have quite as many types of charts that can be done at the time of this, and is one that I have not used as much.
You may also use Draw.io (now Diagrams.net) as a extension in Visual Studio Code or directly on the web to visually create the chart instead of textually.
Create Some Documents
During the planning stage for something, it is nice to have a docs folder available for documenting what you are doing and planning to do. If you did not use the README file option when given the chance on Github, please do so now as README.md. Your file structure should look like the following when done, though without the LICENSE file.
Put useful information into the README
With your project, the convention is to put useful information into the README file. This usually includes the name of the project, a brief description and how to use it along with other information as needed at a broad view. As we are in the planning stage right now, we will fill in just the information that we know. Also, as the file ends an .md extension we can use Markdown syntax and preview what it will look like when formatted. To do so, you may either click the Open Preview to the Side button in Visual Studio Code (it looks like a window with a magnifying glass) or use the combination Ctrl+k and then tap v.
Once you have the preview opened, you may type whatever you want in. I put in the following.
1# Tic Tac Toe 2 3## Why does this repository exist? 4 5This repository is used as part of the adsittech.com practical programming series. At this point in the series, we are learning a bit about planning through doing some planning and execution of a small project. 6 7## What is the student end-goal of this project? 8 9This project's end goal for the student is to have a working game of tic-tac-toe, one that is fully functional to play with two humans, or against a computer. 10 11## How do I use this project? 12 13This project is still being implemented, and as such is not yet functional. 14 15## Folder and File List 16 17- [docs/](docs/README.md) - The documentation for this project, outlining our thought process throughout. 18- LICENSE - This license is here to give permission for the students to do whatever they want without concern. 19 20## TODOs 21 22- Answer how to use the project when possible. 23
Which made the screen look like the following. It should be noted that GitHub will look similar to the right side of the screen if it the readme is pushed now.
A few notes on this example
You will notice that the very first character used is a #. In Markdown, this is used to give a header level between one and six based off of how many are used in a row before the space. As we wanted the first line to become the main title, we used this. Underneath, it is one level of logic deeper than all encompassing, and so it has two in a row. In this example, some starter questions were given as sub-headers along with a TODOs area. The TODOs are clearly missing some things as we still have yet to implement the whole project, but it gives a reminder of what needs to be done. Additionally, we were able to create bullet points using the - character, and links with [text-here](link-here) syntax - in this example, we are doing a relative link to a document that does not yet exist and are not linking to the adsittech.com website as we did not do it in that format. One other important thing - in the Folder and File List section, we are not including the README as that is the current file, and convention dictates it is where written information about the project is kept. Also of note is that it is that it does not need the preview open at the same time to have an idea of what is happening due to some visuals already existing.
For Markdown, what the final text looks like is determined by starting characters and indentations for many of the styles created, allowing a natural reading and similar formatting between both raw text and final text.
Push Changes To GitHub
You now have something started for planning, so you should push to GitHub.
Create Linked File(s)
Since we have a planned file, we should create it so that we can see it. Depending upon your current setup, you may need to make it manually if the shortcut does not work. The shortcut trick is to use the follow link ability (Ctrl + Click the Link) and to see a pop-up stating unable to open file would you like to create it, then click Create File.
After you are done, your folder structure should look like this.
Fill in docs/README.md
We will now need to fill in the newly created README file. This time, we are at a level specific to the documentation of the project. We can flesh out the description a little more, and also add a link back to the main README folder. I like to be able to browse my entire project structure quickly through the browser on GitHub or in the Preview pane in Visual Studio Code, and as such always start non-root levels with an up one level navigation - formatted in a blockquote made by the > character because I like how that looks
Given what we know so far, I came up with the following initial contents for the file.
1> [Up One Level](../README.md) 2 3# docs Folder 4 5This folder contains the documentation for this project. We keep our thought processes for the project here, as well as any design documents and diagrams. They may be linked to inside of the main project files as needed. 6 7## Folder and File List 8 9- [diagrams/](diagrams/README.md) - A place for the diagrams to live. 10- [mechanics/](mechanics/README.md) - Descriptions of the mechanics for this game - in other words, how is it meant to work. 11
We are planning to put a diagrams folder as we know that we will be using a diagramming tool, and a mechanics folder as this is a game. We could have rules, mock-ups, brainstorming sessions, research, or any other number of things in the docs folder, using whatever is making the most sense for how your brain works. When working with a team, we would want to try to standardize something that everyone can follow for a structure, but the important thing is that you can figure out what is needed.
Since we have a start here, do not forget to push to GitHub.
Continue Flushing Out
As we have a few more folders defined, we should create their READMEs as well.
docs/diagrams
We do not yet have any diagrams, but follow our pattern so far, with a plan to have them described later in the Folder and File List
1> [Up One Level](../README.md) 2 3# diagrams 4 5Diagrams used throughout the documentation of this project. 6 7## Folder and File List 8
docs/mechanics
Here we start to ask some questions to be able to flesh out more later, but do not yet have anything there. As it is a game, we know that it has rules, and as it is turn based we know that it has a core loop or sequence that repeats.
1> [Up One Level](../README.md) 2 3# mechanics 4 5How this game works. Here we answer the following questions, and add in more detail as needed. 6 7- What rules make up Tic-Tac-Toe? 8- What is the core loop of the game? 9 - How do we start that loop? 10 - What makes that loop end? 11 12## Folder and File List 13
While we pause to decide how to answer these questions, we decide to push to GitHub.
Answering Questions
At this moment, we have some initial structure, and know where things should go. We had added some questions to answer as this is a game, so we can start to answer those. Let us answer each of these, and see where it leads?
What Rules Make Up Tic-Tac-Toe
At this point, we can do a search for the rules of the game, as it is a well known one. If you search for this, you will find that there are also many variations available. As such, we want to make sure we have a set of rules in place that we can follow easily later should we forget, and so make the following entry to our mechanics file list, and add it in.
1- [rules.md](rules.md) - The rules of this game. 2
docs/mechanics/rules.md
1> [Back To README](README.md)
2
3# Tic-Tac-Toe Rules
4
5The rules of the game, formalized so that we do not need to worry about the variations.
6
71. This game has two players.
82. Either player may start the game.
93. Starting player may choose `X` or `O` character to represent their chosen positions.
104. Non-Starting Player gets the character not chosen by the Starting Player.
115. The game is played on a 3x3 grid for a total of nine positions.
126. Players take turns.
137. A turn consists of choosing one open position.
148. The game is over when any of the following is true:
15 - There are no more open positions.
16 - A player has won at the end of their turn.
179. A player has won through having three positions occupied in a row either diagonally or orthogonally.
1810. The game is a draw if there are no more open positions, and no player has won.
19
Notice that, since we are in the same folder, we go back to the README instead of Up One Level. Also, we did not do a specific sequence of rules, but just defined everything that we could.
What is the core loop of the game?
After looking at these rules, we do see something that happens in an alternating way, along with a start and stop.
As such, we decide to make a diagram, showing this sequence. Using PlantUML to do this, we decide to create the following file in the docs/diagrams folder.
1- core-game-play-loop.puml - A diagram showing the core loop of the game. 2
In order to make sure that our Visual Studio Extension is properly configured, we decide to copy the example diagram from the website, and see what happens when we paste it into the file, then use the Alt+d shortcut to preview the diagram. (Also available through the View->Command Pallet->PlantUML Preview Current Diagram menu sequence)
1@startuml 2Alice -> Bob: Authentication Request 3Bob --> Alice: Authentication Response 4 5Alice -> Bob: Another authentication Request 6Alice <-- Bob: Another authentication Response 7@enduml 8
If all goes well, we should see a diagram on the side.
Once we have that working, we will then start to make our own. Looking through the examples, we see that we can add some Participants as Actors which look like stick people, as well as make a loop. In our rules we see that there are two players and decide to make them show up as Actors... but after playing around a little while.
Thinking over our loop, and researching on the site a bit we end up with the following.
1@startuml 2' Two actors as players, giving an alias for simplier writing later 3actor p1 as "Player 1" 4actor p2 as "Player 2" 5 6' The grid the game is played on 7participant grid as "Game Grid" 8 9' The core loop of the game 10loop While Game is Not Over 11 alt Player One's Turn 12 p1 -> grid : Choose an open position 13 p1 -> p2 : Change to Player Two's Turn 14 else Player Two's Turn 15 p2 -> grid : Choose an open position 16 p2 -> p1 : Change to Player One's Turn 17 end 18end 19@enduml 20
Basically, we end up with a loop that has the same thing for Player One and Player Two along with a quick description of what is happening. We can see this very visually, and so now want to use this diagram to answer our question from earlier.
Before figuring out how to insert it though, we push to GitHub.
Some Notes On This Diagram
In this diagram, we are organizing the order we want Participants to appear and have given alternate display names from the diagrams given. We created a loop with the same basic code twice, but it could be reduced further with the alt not there if we were to name the Actors Current Player and Non-Current Player or something similar. We can also add a section for checking if the game is over. However, the goal here is to be able to quickly see what our main loop will be like when playing the game, as well as to get an idea of some things that can be done with PlantUML.
Exporting the Diagram to Display Somewhere Else
We want our diagram to be available aside from in the preview pane, no matter where we look at the documents, and so we decide to export it. This may be done through the Ctrl + Shift + p combination, and picking PlantUML: Export Current Diagram.
I recommend either as a .png file or .svg (svg changes size to fit where it is, and stands for Scalable Vector Graphics).
No matter which you pick, you will find the results in a folder that is somewhat unexpected - out/docs/diagrams/core-game-play-loop.
Keeping the Diagram out of Source Control
As we want to control the location of the diagrams a bit better, and may later wish to batch create images which will still output to this location we decide to add a file to the root of the project called .gitignore. This file is used to tell git what files to ignore, and will contain the following content.
1# Ignore generated output 2out/* 3
Now, you may be curious as to what this did. Some files in the file tree have turned grey, and your .gitignore file is green now while the git branching icon shows just 1 still.
This is because even though there are new files, the only one that is noticed by the source control now is .gitignore, the out tells the folder, with /* saying everything inside the folder. We should push to GitHub now.
Note that your .gitingore file is now matching the others that have been checked in, and the out folder is still greyed out.
Using the Diagram in our MarkDown
With that, we now need to move the output diagram next to the original puml file, since that matches our structure so far.
We should update our diagrams folder README as well to reflect the diagram has been put in using another format. I chose to keep the .svg file, as it scales well, so my docs/diagrams/README.md now is as follows.
1> [Up One Level](../README.md) 2 3# diagrams 4 5Diagrams used throughout the documentation of this project. 6 7## Folder and File List 8 9- core-game-play-loop.puml - A diagram showing the core loop of the game. 10- core-game-play-loop.svg - An SVG version of the core loop of the game, for embedding elsewhere. 11
Now that we have a visual of what should happen, we decide to go ack to our docs/mechanics/README.md and answer the remaining questions. Looking at our current organization, we decide to make a new sibling file, similar to rules.md but instead called core-loop.md and insert the following.
1> [Back To README](README.md)
2
3# Tic-Tac-Toe Core Loop Questions Answered
4
5The core loop of the game, formalized to more easily create a project from. It answers our questions from the main readme.
6
7## What is the core loop of the game?
8
9
10
11## How do we start that loop?
12
13The loop starts upon a new game beginning, after the starting player has chosen their character, `X` or `O`.
14
15## What makes that loop end?
16
17The loop ends once the game is officially over. See [rules](rules.md) for more detail.
18
When you open the preview for core-loop.md, you should see your diagram there - using the link syntax with a ! before it causes an image to be put in, with alt screen reader text of what the link text would normally be.
Do not forget to add the core-loop.md to the mechanics README file and push to GitHub. Now that we have all of the information, it might be nice to do a more full summary there as well. My final docs/mechanics/README.md looks like the below.
1> [Up One Level](../README.md) 2 3# mechanics 4 5How this game works. Here we answer the following questions, and add in more detail as needed. 6 7- What rules make up Tic-Tac-Toe? 8- What is the core loop of the game? 9 - How do we start that loop? 10 - What makes that loop end? 11 12## Folder and File List 13 14- [core-loop.md](core-loop.md) - The main loop of the game. 15- [rules.md](rules.md) - The rules of this game. 16 17## Summary of Usage 18 19The answers at the start of this document are answered through the files linked. To use this, we should look at the [core-loop](core-loop.md) and the [rules](rules.md) in tandem, starting with the conditions to start and end the loop, and finally creating the loop itself. 20
Finally, we should be able to do one last push to GitHub to complete our initial planning session.
Summary
At this point, we have a reasonable amount of starting documentation and may start seeing what we should implement from here. As we create the game, we will be finding out new requirements based upon the experience, and see other things that may have been helpful to plan out before hand as we gain more knowledge and the ability to do so. You may view the current code on GitHub or StackBlitz
Next - Implementing a Project - Tic-Tac-Toe
Prior - Web Page Interactive Button Code Investigation Continued
Tags: Practical Programming, MarkDown, Planning, PlantUML, Tic-Tac-Toe