The Importance Of Glossary

Try to refer to the Solitaire’s deck of cards that appears in the top left corner. Now try to distinguish the cards that were not drawn, the cards that were drawn, the cards that were drawn but now are not visible due to the newly drawn cards. Now do it repeatedly over and over again for each of the Use-Cases that handle these elements. And that’s just one gameplay element.

I decided to create a new Glossary section where i’d first define each of the game elements, starting with their name and location. Since the game-element mechanics is known, it will be enough to distinguish one from another them. However, for future projects in which I would go for not so defined gameplay, the behavior and purpose of theses objects must also be written down.

Revisions Section

I like to backup my work every hour or so. I also work on more than one folder and on several computers. This document took more than 2-3 sessions of writing since I can only dedicate 30 minutes or so everyday. Each session generated more text, but left some loose ends which I had to take care for the next sessions: more Use-Cases, undefined elements.

Instead of leaving a seperate Todo list and taking the time to remember what i’ve already done, I started a Revision section at the start of the document. For each session I wrote the changes I’ve done and the work needed to be done for the next session. For the next session, it took me less time to “recalibrate” myself on the work that’s needed.

Separating The Two Games

The first draft contained the definition of both game’s mechanics. It was horrible since it kept jumping between the two game’s Use-Cases describing a Hybrid game. Also, the fine details that defined each of the games were left behind since most of my concentration went on focusing on two separate games – what belongs where. The common parts were the worst – each had tons of exceptions referring to each of the games.

I decided to separate the design process of the two, observing which of the parts are similar or even the same for later pre-coding design where I would be able to use the same code for both games.

Both of these classic games are pretty much comprised of the same mechanics: a deck of shuffled cards which has to be re-organized into 4 stacks of ascending-same-suit cards. In the course of the games cards are needed to be arranged also in ascending order, however in a stack of alternatly-changing red/black order.

Learning from the Minesweeper Speed Challange I decided to start the design process with Use-Cases. There will be a single Use-Case document for both of the games defining the common Use-Cases in a joined section and the specific Use-Cases in a seperate section. This time, I plan to follow this stage with a Class-Diagram that will contain each of the processes defined in the Use-Case document and by the GUI.

The solution file will also consist out of three projects: Solitaire, FreeCell and the Common Assembly that will contain the features that are common to both games as defined in both the Use-Case and the Class Diagram. The common assembly is to be written so that it will be able to be re-used in a (possible) future project without any modification.

Minesweeper Application

Staying concentrated and task-oriented at the end of a work day wasn’t easy. However, since the entire design was well-written as Use-Cases. Each Use-Case was a function or a module and their contents was laid out as comments inside to follow each line or two with the code. However, the final touch-ups did not appear in the Use-Case as I thought. Highscores and Custom games were not mentioned and were programmed in a single session without pre-design or documentation.

Since these features were not documented, I did have to invest more time and be more alert writing slightly more complex code. Heck, it took about 10-15 minutes more – but considering the fact that this was a pilot for a large-scale project, I think it might work for the best to come back to the drawing board before adding / changing significant features.

Debugging took less time as well – most of the scenarios were well thought in the design stage of the Use-Case and covered about 80% of the bugs I usually end up fixing in this stage. It will be more interesting to re-program a more complex past project such as Checkers / Chess (with AI) to test whether time spent on Use-Cases takes less time than fixing the errors caused by not using them. In such small scale project, the time spent on either is insignificant but does give insight on the time it will take on larger projects.

I’ve attached the application here for impression: Minesweeper

Enjoy!

Minesweeper code

About 80% of the methods i wrote involved translating 2-3 sentences in English into C#. Since most of the logic was already encompassed within those lines, it allowed me to steamroll through the code without straying through the design process.

Even though the task of writing the code took much less time, the code came out much more organized and well documented.There were a few processes which the Use-Cases did not cover such as the GetNumberOfSorroundingMines(). I admit that I did not had them in mind while writing the Use-Case document.

I found that they contained absolutely zero comments. But since they contained such a low code complexity – writing such amount of Use-Case and code comments will be either a design overkill or unnecessary time overhead to such secondary code.

Minesweeper non-Use-Case method

I found it most useful to use the NotImplementedException as a bookmark to jump between implementation of methods. Some of the Use-Cases contained references to other and in some cases I had to take actual breaks which left loose-ends in my code.

NotImplementedException

A few more features are left such as the High scores table and the game timer, but other than that – the minesweeper is pretty much done

I tired to be more productive without being over perfectionist, following a defined format for each Use Case so I won’t get over-zealous with the design and sticking to the standard.

Here’s what I came up with:

Use Case: Create New Mine Placement Board

Activating Actor: The System.

Description:  The system asks for new placements of mines on the board. This should not be confused with Use Case: Create game which initialized the board shown to the user and the user markings.

Preconditions:

• A board size must be set.
• Number of mines for this board size must be set.
• The number of mines should never be equal or greater to the number of squares on the board minus the first selected square.

Basic Flow:

1. Create a list of the possible locations.
2. Create an empty board according to the board created in the last Use Case: Create game.
3. For each mine needed:

• Remove a random location from the possible location list
• Mark a mine on that location

1. Initialize and Start the game stop-watch.
2. Reset mine marked counter.

Exceptions:

None, so far.

Use Case: Clear Mine Square

Activating Actor: The User, and in case of [Exception 4.1], The System.

Description: The user left-clicks a square to clear it and test whether it contains a mine.

Preconditions:

• Square is on the board.
• Game has not won yet.
• Square has not already cleared.
• Square is not marked as containing a mine by the user as described in Use Case: Mark Possible Containing Square Mine.
• Check for game end condition as described in Use Case: Check for Win.

Basic Flow:

1. User left-clicks a square.
2. If no square has been cleared before, create new board to make sure no mine will ever explode on the first clearance – refer to Use Case: Create Mine Placement Board.
3. Check if a mine is located under this location
4. Show the number of mines surrounding this square.

Exceptions:

3.1. [A mine is located underneath this location]

• If so, end the game – refer to Use Case: Game Lost.

4.1 [The number of mines is 0]

• Activate this use case recursively for each of the surrounding  squares.

Use Case: Clear Surrounding Mine Square

Activating Actor: The User.

Description: The user to clear every surrounding square according to Use Case: Clear Square.

Preconditions:

• Square must be on the board.
• Game has not won yet.
• Square must already be a cleared square according to Use Case: Clear Square.
• The number of user marked squares according to Use Case: Mark Possible Containing Square Mine surrounding the selected square should be equal the mines declared on the square.

Basic Flow:

1. The user releases both right and left mouse buttons on a square.
2. Every surrounding square is cleared according to Use Case: Clear Square.

Exceptions:

• None so far

Use Case: Game Lost

Activating Actor: The System.

Description: Once the game is lost, show every mine marking and non-mine marking on the visual board.

Preconditions:

• A mine-placement board must have been created.

Basic Flow:

1. For each of the visual squares:
   1. Remove any player marking on the mine.
   2. Display the number of mines underneath or a mine present.
   3. Stop the game stop-watch.

Exceptions:

• None so far

Use Case: Check for Win

Activating Actor: The System.

Description: The system checks whether the player has successfully finished the game.

Preconditions:

• Every square had either been cleared as described in the Use Case: Clear Square or had been marked as described in the Use Case: Mark Possible Containing Square Mine.
• The mine counter is 0.

Basic Flow:

1. Check if every marked mine location is right.
2. End the game.
3. Check For a new High-Score.
   1. If it’s a high-Score, replace the current one.

Exceptions:

1. [a mine is located in an incorrect location]

1.1. Continue the game and stop at [1.]

Use Case: Mark Possible Containing Square Mine

Activating Actor: The User.

Description: Player right-clicks a square to remember that it might contain a mine.

Preconditions:

• Square is on the board.
• Square had not been cleared as described in Use Case: Clear Mine Square.
• Game has not won yet.

Basic Flow:

1. User right-clicks the square.
2. The system marks the square.
3. Check for game end condition as described in Use Case: Check for Win.
4. Decrease mine marked counter.

Exceptions:

1.1. [A Square has already been marked as containing a square mine]

• Unmark it.
• Increase mine marked counter.

Use Case: Create New Game

Activating Actor: The User.

Description: The User wishes to start a new game.

Preconditions:

• None so far

Basic Flow:

1. The user selects one of 3 difficulties:
   1. Easy : 10×10 Board with 10 mines.
   2. Medium: 16×16 board with 40 mines.
   3. Hard: 30×16 board with 99 mines.
   4. According to [1.]:
      1. The system redraws the screen.
      2. Clears any marking on the visual board.
      3. Resets the stopwatch.

Exceptions:

• None so far

To send a 9 bit through the serial port is pretty easy: Send the first 8 bits normally with either a Mark(=1)/Space(=0) parity setting for the extra 9th bit.

The hell I went through involves SENDING each 9 bits, and this is where my story starts…

Using the .NET SerialPort Class

To recieve byte, I set my serial port to a Space(=0) parity setting, and for each byte I would check for a parity error. No parity error = 9th bit 0, whereas a parity error = 9th bit 1.

Sounds easy, right? WRONG!

.NET Serial Class gives you 2 interfaces to identify parity errors. The first is an event called ErrorRecieved which according to MS:

ErrorReceived events may be called out of order, and there may be a slight delay between when the underlying stream reports the error and when code can when the event handler is executed.

The ErrorReceived event is raised on a secondary thread when an error is received from the SerialPort object. Because this event is raised on a secondary thread, and not the main thread

According to this and the event delegate signature, when a parity error occures you can not rely it will happen in a reasonable time nor will you know on which of the bytes the error had occured.

Second way is to use the ParityReplace member which quite effectively, replace a parity errored-byte into a value of your choosing. This allows parity detection for the price of the 8 bits it follows. No good as well.

Using Windows API functions

There’s a bunchload of Serial Port related resources about P/Invoking a lower-level Windows API functions to handle serial-port communication, which hopefully give me some solution to my problem.

So I wrote a new SerialPort class which encapsulates the P/Invoke’ed Win32 API functions using some nice examples across the web. This time, detecting a parity error went without a hitch, I’d ReadFile a single byte from the port and then check for the last error for a parity problem. Another nice touch is to use the fAbortOnError member in the DCB which stops all read operation upon stumbling an error (specifically, a parity error).

This proved to be a working solution, until it was used under the production environment. It appeared that detecting parity errors (the 9th bit) worked inconsistently. Further inspection of both the program and the web, revealed that the root of the problem lies in a much lower level – the windows serial.sys device driver.

The Serial Port Device Driver

Every unhandled incoming data recieved by the serial port is queued into the driver FIFO buffer to be handled by the next API read. Whoever wrote this driver, only queued the recieved bytes and not the recieved data (both the 8 bits and the parity bit). So if your program is polling information fast enough not to let any byte enter the buffer you’re safe, and if you plan any other non-serial-polling-software-centric you’re not.

So i turned to the Windows Driver Kit to revise the current serial.sys (code included with the WDK) driver to fit to my needs. It took a while, but now when the serial port recieves a byte, it enqueues two bytes: the recieved byte and the parity.

Problem solved.