Design and Code – Part 7 – Implementing ‘Auto120’ in Javascript

This is the seventh in a series of blog posts I’ve been working on during COVID isolation. It started with the idea of refreshing my systems design and software engineering skills, and grew in the making of it.

Part 1 describes ‘the problem’. A mathematics game designed to help children understand factors and limits which represents the board game Ludo.

Part 2 takes you through the process I followed to break this problem down to understand the constraints and rules that players follow as a precursor to implementation design.

Part 3 shows how the building blocks for the design of the classes and methods are laid out in preparation for understanding each of the functions and attributes needed to encapsulate the game.

In Part 4 we get down to business… producing the game using the programming language PHP with an object orientated approach.

Part 5 stepped it up a notch and walked through a translation of the code to object orientated C++.

Part 6 delves into the world of translating the code into object-orientated Java.

In Part 7 the same code is then translated into Javascript. Read on!

Get in touch on Twitter at @mr_al if you’d like to chat.


Javascript

Available on GitHub at: https://github.com/mr-alistair/ootest-js

Run-time available at: http://alistairlloyd.com/ootest/js/

So – Java to Javascript – that would be simple, right? It was. By this stage I’d gotten into a rhythm of finding the things that I was going to trip over when changing from language to language and knew to start by experimenting and targeting the areas I’d figured were dramatically different.

Javascript is not Java. If anything, Javascript looks like C++ and PHP had a kid and raised it in a land where they speak HTML. Calling it a ‘script’ is doing it a disservice, though. It can certainly do a lot of the heavy lifting at the ‘front end’ of a web-based system and let PHP and other code handle the ‘back end’. (I haven’t gone into the front end wonders of jsquery or server-side entertainments like node.js here. Maybe one day soonish.) And with modern browsers you have built-in debugging to boot, so that was a bonus.

It was time to consider a different IDE, which had also emerged as a theme of what I was exploring. I went with Visual Studio Code, the street-wise younger sibling of Visual Studio. There were some set-up things which were interesting. Visual Studio Code has a set of plug-in Extensions which provide additional syntax and debugging support, and some run-time libraries for languages that need it. My client browser would execute the Javascript, so VSC needed to know this:

Figure 1 – Workspace configuration in Visual Studio Code… dark mode… such edgy, much black. Wow. Additionally… telling tool where to launch test code from (via Chrome, calling index.html in the workspace folder).

There was also a great Debugger for Chrome (by Microsoft) which helped when stepping through issues within the IDE. All set.

Object Orientated in Javascript

Object Orientated mechanisms in Javascript, for web-based solutions, meant that instead of the standard ‘wrapper’ Class that I’d built to trigger proceedings in other languages (usually a Class named Auto120), I had a HTML file instead. This had two <script> blocks – one to hold the src calls to the three Class modules, and one to execute the game.

Some key differences from the start included:

All variables need to be declared up front as a var , or cannot be referenced without Javascript thinking that it was a procedure call. Like PHP, these variables were loosely typed. The pedant in me usually declared and assigned them a value, such as 0 or “” to remind myself what they were supposed to be.

Where Java required an instance of a Class to be declared by the Class name [i.e. Game thisGame = new Game();  ,  Javascript needed this to be declared as if it were a variable, i.e.  var thisGame = new Game();

In the C++ and Java versions I was used to piping output to the standard terminal output channel; in Javascript it was back to rendering it as HTML. So, it was <br> instead of \n . At least string concatenation was easier, using “+” in the same way as “.” is used in PHP. Standard Javascript ‘document.write’ was used for writing browser output.

Class procedure definitions took me back a step, however, as Javascript reverted to the “this” precursor to identify the ownership of each property or method.

Defining arrays introduced me to the ‘push’ call, which I thought I had put behind me with an ill-fated foray into Assembly language as a teenager. Populating an array of Player Markers became an iteration around:

 this.p_pieces.push(new Marker(x_counter));

…where x_counter sequenced from 0 to 4. Yep, we only wanted to deal with Markers 1 to 4, but I cheated and filled in the first array position, 0, as well.

Totally random

A new language to explore meant a new way of figuring out how to generate a random number. For Javascript this ended up being a nesting of two of the implicit Math-class methods – random, and floor.

Math.random will return a floating point value. Multiplying this by the given upper-boundary integer will produce… a larger floating point value. This is great if you want an answer of 4.323 or 2.534 … but I wanted a nice, clean integer between 1 and 6 inclusive. Enter Math.floor which returns the largest integer less than or equal to the current number. Great! As it’s the lower boundary, however, we need to add one to it to bring the lowest possible value up from 0 to 1. So, we end up with:

Presto. One random number between 1 and ‘g_upper’ inclusive.

Back to arrays

Arrays had me pulling my admittedly sparse hair out a few times, particularly where null values or out of bounds results were causing fatal errors. This is where old-school stepping through code during debugs and setting ‘watch’ on variables can be a life saver. I was used to iterating through an array and referencing positions 1 through to 4; most of the arrays I was dealing with expected a value at position 0 as well, otherwise making a reference to the array ‘as a whole’ would trip the wire.

A simple/inelegant fix was to ‘push’ a dummy value to position 0 on the array prior to getting down to business. This value was to be ignored anyway, and for the sake of a few bytes of memory, I was happy.

Two dimensional arrays were just as fun. The breakthrough came when I realised that a two-dimensional array was effectively one array with another array ‘pushed’ into it several times. (My mind keeps thinking of that American culinary delicacy, the Turducken, but we shall not speak of this, here.) So:

…gives us the two dimensional array x_forecast_pointers which, at position 0, has an instance of array x_forecast_internal. A later loop (not shown here) then pushes additional instances into x_forecast_pointer by setting the values within of x_forecast_internal and pushing them into the next available position. I was legitimately surprised that this worked.

When it came to searching for values within an array, I fell back to iterating through the array sequentially. There is an array find() function but, when considering code portability, it is not supported in IE11. Mind you, I’m not particularly supportive of IE11 either, so we’ll call that one a draw.

Making a true independent copy of an array was far easier using the array slice() method, vis:

Walking the talk

So, they were the big-ticket items. Testing the code proved interesting, as with most browser-based renderings one typically must wait for the code to complete before it starts ‘writing’ anything to the document… in this case, the HTML page. It was fortunate that the Visual Studio Code IDE has a built-in console interface that you could output to which helped when it came to stepping through things.

The issue with this is that sometimes code got stuck in a loop (my usual problem of poor punctuation, generally due to missing a bracket on an iterator) and so it appeared to ‘freeze’ after it had flushed output to the first page of so of HTML. Tracing these, particularly with nested conditionals and repeated call-backs is a tedious exercise – it teaches one a wax-on, wax-off lesson about cautious coding, and alcohol consumption while doing so.

The verdict?  I didn’t mind JavaScript at all. I gained an improved appreciation of where it ‘sat’ in the big scheme of full-stack development for web-based apps. Down the track I’ll take a closer look at node.js and jsquery, but for now I had another serpent to wrestle with…

NEXT POST… Python! Would this slippery beast prove my undoing? Find out next time…

Design and Code – Part 6 – Implementing ‘Auto120’ in Java

This is the sixth in a series of blog posts I’ve been working on during COVID isolation. It started with the idea of refreshing my systems design and software engineering skills, and grew in the making of it.

Part 1 describes ‘the problem’. A mathematics game designed to help children understand factors and limits which represents the board game Ludo.

Part 2 takes you through the process I followed to break this problem down to understand the constraints and rules that players follow as a precursor to implementation design.

Part 3 shows how the building blocks for the design of the classes and methods are laid out in preparation for understanding each of the functions and attributes needed to encapsulate the game.

In Part 4 we get down to business… producing the game using the programming language PHP with an object orientated approach.

Part 5 stepped it up a notch and walked through a translation of the code to object orientated C++.

Now in Part 6 I do the same thing, but in the world of Java.

Get in touch on Twitter at @mr_al if you’d like to chat.


Java

Available on GitHub at: https://github.com/mr-alistair/ootest-java

I’ve never officially been ‘taught’ Java. I missed out on that from a University perspective by a few years and was only ever exposed to the compiled after-math in the ‘90s and ‘00s.

Overcoming prejudice

My feelings about Java have been mixed. Early exposure in the corporate world was to chunky Windows-GUI analogues that didn’t look as polished a their C++ or VB peers, leaky unix-based apps that required regular garbage-dumps that would freeze activity system-wide while they took out their memory-trash, and intimidating thread dumps that provided wholly unsatisfying evidence as to what had actually gone wrong, and why.

Figure 1 – A bit of nostalgia; likely to have been be the first exposure to the joys of Java for many of us. What does this even mean? It’s a mystery wrapped in an enigma.

In terms of technical prejudice, my inner sceptic had become wary of any solution that positions itself as being pan-platform, write-once-run-anywhere, saviour of all developers, etc. The hype of so-called ‘5th General Languages’ (5GLs) in the ‘80s had also made me wary. The reality of having to specifically match a range of different Java Runtime libraries based on the vendor, platform and operating system simply meant that did not live up to the hype. (I was particularly scarred by trying to get an enterprise integration platform up and running in a Production environment, and the darn thing just would…not…start. Turned out there was a minor (I’m talking x.x.00n) version difference in the Java runtime libraries between the non-prod and prod environments, and that was all it took.)

Oh, and the typeface on any GUI implementation always left me cold… felt like I was back in the 16-bit graphics days. Nostalgia will only get you so far.

Forearmed

Armed with my knowledge of what was different between PHP and C++, I had a better idea of what I would face in converting the algorithm to Java. My first move, however, was to look for an appropriate IDE. I tried in vain to find suitable project plugins for Visual Studio which matched the toolkit I’d used when coding in C++. Having previously attempted to code Android Java in Eclipse, I downloaded that instead and got to work.

Figure 2 – Example of the Eclipse for Java IDE, stolen from the website of the Computer Sciences faculty of the University of Wisconsin-Madison

Translation from C++ to Java

The transcription was far easier than I though it would be. The syntax and grammar of the languages was a lot closer than anticipated, save for the nuances between how things are defined. It’s a bit like the difference between German-German, and Swiss-German. Close, but with klein aber fein differences.

Class definitions and internal references to properties did not require the use of ‘this’. Clearly it was self-evident to Java that ‘this is mine’ was the default and did not need to be explicitly mentioned.

As for Booleans, False was false and True was true. Easy.

Classy Arrays

Instantiating an array of another Class took me a few goes as I was over-complicating it. Java allowed the simple call of:

       Marker[] p_pieces = new Marker[5];

…to tell the compiler ‘this property will be a 5-element array of class type Marker’. As a BASIC programmer from way back, it took me a little while to get used to having to define a property as a type of the Class you were about to tell it that it was, anyway. It was not helped by online articles and help-support topics that showed it like so:

               Classname classname = new Classname;

(or, more frustratingly:                 Foo foo = new Foo; )

This always tripped me up… especially when the writer would give the property/variable name the same name as the Class. Took me a lot of trial and error (and stackoverflow trawling) to realise that there were a few things going on here. Simply declare the property, and you end up with a null property. Declare AND instantiate it at the same time, and you get a property that is enlivened with whatever the Constructor method for that Class provides.

Two dimensional arrays followed a similar path. In the Game class method g_target_magic_numbers there was a need to instantiate a two-dimensional array of integers. After some mucking about this ended up being simple:

       int[][] x_forecast_pointers = new int[5][3];

What I realised earlier, though, was that the element values in this array needed to be set BEFORE they could be referenced, or a null pointer error was returned. So, for one-dimensional arrays where a value may or may not be filled, it was a case of saying up front:

int[] x_piece_array_pointer = {0,0,0,0,0};

Making a hash of it

Searching for the existence of a value in an array gave me the chance to try out a different method – hashing – which research had informed me was a more efficient over iterating across the entire array.

Establishing a hash set from an array of values involved including the following class libraries, and making the following calls:

import java.util.Arrays;

import java.util.HashSet;

    final Set<Integer> x_temp_magic_numbers = new HashSet<Integer>();

x_temp_magic_numbers.addAll( Arrays.asList( 20,24,30,40,60));

So now we have a hash set named x_temp_magic_numbers that contains the five values.

Returning a Boolean when searching for a value within this hash set occurs through:

x_test_1 = x_temp_magic_numbers.contains(x_player.p_pieces[x_temp_value].m_get_location());

[vis, return a true/false IF the location of x_player’s piece number x_temp_value (which is identified through the method m_get_location) exists in the hash set held by x_temp_magic_numbers]

At this point, I was pining for PHP’s “in_array” method.

Do what I say, not what I intend

Copying arrays was also straightforward…but came with another hitch. Initially, I did the following:

System.arraycopy(x_piece_array_pointer, 0, x_piece_array_backup, 0, 5);

I’d tried to be economical (read: lazy) and ignore array position zero as I was only interested in the values in positions 1 through to 4 – the array of Markers for each Player. I even left myself a prompter note in the comments:

//hopefully won’t fail as index 0 is not set

A few hours later, this comment read:

//hopefully won’t fail as index 0 is not set  //well…it did…

..because of exactly what I had predicted. In a Java array, even if you have happily populated 4 out of the 5 elements… if one element is null, then a method such as arraycopy will crack it. Also, the final integer passed to arraycopy is the total length of the array, not a pointer to the final index (which would typically be 4).

What arraycopy did do (when I corrected my issues of having null elements) was to create a true new instance of the array, rather than a pointer to the original one. This took me a while to work through, as if I’d simply said “this array [equals] that array” it would assume that I wanted a logical reference, not a fresh and independent copy.

Random variations

Getting an integer random number was fun. I used the java.util.Random library and generated it like so:

             Random r = new Random();

return r.nextInt(g_upper) + 1;


The second line takes some explaining. Random() by itself sets a seed and initiates the random number generator. nextInt(value) generates an integer between 0 and the provided value (in this case identified by the variable ‘g_upper’)…minus 1. So, if you want a random number like a die roll, you need to get the method to add one to the value generated.

Java coded packages tied up with strings

Couple of final things in the Java world: strings and concatenation were easier to handle following my traumas with C++. The difference being the need to explicitly call the ‘toString’ method before the Integer class of the object, even though the variable object was an Integer. For example, in the logging method:

g_logmove(“Player ” + Integer.toString(g_playerturn) + ” will go first.“);

Formatting date/time in the logging method took a bit of tweaking as well. Rather than trying to squeeze it all into one line, I broke it up for readability.

Integer x_movecounter = this.g_movecounter;       

DateTimeFormatter dtf = DateTimeFormatter.ofPattern(“yyyy-MMM-dd HH:mm:ss“); 

LocalDateTime now = LocalDateTime.now(); 

String x_timestamp = dtf.format(now); 

g_movelog[x_movecounter] = (x_timestamp + ” — ” + x_logmove);

Wrap up

Some interesting observations – Java did not suffer the same random-seed issue that I had experienced in C++. I was able to punch out to a command line and execute it from my workspace using:

       java -classpath Auto120 Auto120.auto120

…which enabled me to capture some interesting stats on repeated runs which I’ll discuss in a later post.

And, indeed, I was able to pick up and run the code on an Ubuntu Linux installation with no modifications. Heh – turns out what is written on the side of the pack is true. Go figure.

Java was a bit of fun, and by now I was seeing a regular pattern in the things that differed (or aligned) between the languages. Therefore, translating from Java to Javascript should be pretty straight forward, right? Right…? Hello..? (taps microphone)

NEXT POST… Javascript. It’s not quite Java, and it’s not a pure scripting language. So what gives?

Design and Code – Part 5 – Implementing ‘Auto120’ in C++

This is the fifth in a series of blog posts I’ve been working on during COVID isolation. It started with the idea of refreshing my systems design and software engineering skills, and grew in the making of it.

Part 1 describes ‘the problem’. A mathematics game designed to help children understand factors and limits which represents the board game Ludo.

Part 2 takes you through the process I followed to break this problem down to understand the constraints and rules that players follow as a precursor to implementation design.

Part 3 shows how the building blocks for the design of the classes and methods are laid out in preparation for understanding each of the functions and attributes needed to encapsulate the game.

In Part 4 we get down to business… producing the game using the programming language PHP with an object orientated approach.

And now in Part 5 we step it up a notch and translate the code to object orientated C++. Read on!

Get in touch on Twitter at @mr_al if you’d like to chat.


C++

Available on GitHub at: https://github.com/mr-alistair/ootest-c-plus-plus

A short history of study and the Internet…

I took myself to University as a so-called ‘mature age student’ (I was 23 years old…so mature, so very mature…) and did night-classes for 5 ½ years to get my Bachelor degree in Computing.

By this stage I had been exposed to computers half my life, had self-taught myself BASIC and some COBOL, and had spent most of that half-life exposed to two extremes of computing. At one end were early self-contained personal computing systems (i.e. Sinclair, Commodore, Apple II, and what were then called ‘PC-compatible’, later known as Wintel systems (before Windows became a Thing)). At the other end were the big-end-of-town industrial strength mainframes (ICL, IBM) running VME and MVS respectively.

Figure 1 – ICL Series 39 Level 80 mainframe. Some of the more contemporary disc storage was a whopping 256 Megabytes.

I was fortunate in my timing of arriving as a (“mature”) University freshman in 1995. This thing called the Internet was on the rise and was starting to break out of the confines of DARPA and education institutes and find it’s way into the world. As a result, my early studies of software engineering were through learning HTML and C. Not C++ … we heard about it later, of course – just C.

So, it was with this aging and basic understanding of the syntax and rules that I set about converting the object orientated version of what I now called ‘Auto120’ to C++.

Avoiding getting lost in translation

Following PHP, C++ struck me immediately due to its discipline. That there were syntactical similarities with PHP was pleasing to me. The self-referential use of ‘this’, the -> arrows to indicate properties within Classes, and the use of curly brackets, to name a few. The typing of variables – and having to explicitly identify an integer or a Boolean – meant taking a closer look at my code to avoid assumptions around how each variable would be treated.

A major difference between the two languages was needing to identify which general Class libraries to include in order to get what I would consider ‘basic’ methods to work. By this, I mean: strings, date/time methods and some array iterators. This took some trial and error, and a fair bit of time trawling Stackoverflow. (Praise be).  

The Hit List

It was during my code migration from PHP to C++ that I realised that there was a recurring “hit list” of things were that were going to be different for each language. Once I had identified how to implement these, the rest would be easy*  (*it wasn’t easy, I was just idealistic). They were:

  1. Instantiating an array of another Class
  2. Instantiating a two-dimensional array
  3. How strings and integers were parsed and concatenated into a longer string
  4. Generating random integer numbers
  5. FALSE, False, false and 0
  6. Setting iterative ranges
  7. Searching for a value in an array
  8. Copying an array (without creating an array of pointers to the original array)

These eight items became my prove-yourself entry-criteria that I set myself to ensure worked as I took on each subsequent language.

History, Part 2

Side story: There was a gentlemen who worked with me in various projects and departments at a few different companies. He was a software engineer, one of the best I’ve ever worked with. He was never happier than when he had his headphones on and a juicy set of technical problems to solve. You’d give him one problem to solve, and he’d return it to you, fixed, along with three other problems he’d found along the way that no-one had realised were there before. And as he walked back to his desk, he’d say: “Oh… and it runs about ten times faster now, too…”.   No ego, no arrogance. Just a master craftsman in his prime.

One day, I asked him about career aspirations and the opportunity to become a manager. He recoiled at the idea. Not for him. Programming and software engineering were his things, and he was perfectly happy doing that. “You see”, he explained, “all programming is the same. They just change how they do something. I know how to program. The language doesn’t matter. Once you learn the basics, you can do any programming in any language.”

This from the guy who would take home a book on a particular language, read it overnight, and then churn out reams of bug free and efficient code the next day on a platform he’d never used before.

I thought, then, that he was an exception. Having now gone through this exercise with six different languages, I know now that he was right. It’s the same. The syntax and variations alter with the whim of the language designers, but the basics remain.

Coda: Notably, when I was at a company implementing the SAP ERP, I asked him how he was going learning the new platform. He smiled and said: “SAP… it is like it is a big house, with many rooms. And each room – ECC, SRM, CRM, etc.  – has been decorated by a different person, with different wallpaper, carpet and furniture.”.  This is a great analogy for any complex system that has been built or acquired in modules over time. As I often say in my corporate life, “The best thing about our standards is that we have so many to choose from…”.

Back to C++

Back in the 90’s (no, not the start of the BoJack Horseman closing theme… but try to get that out of your head, now) we cash-strapped under-grads had to fork out $89.95 for a “student edition” of Borland C++ which came in a neat box with a finely-printed manual and about 30 x 3 ½ “ floppy disks to install it. This was an ASCII/Text based GUI, with garishly coloured block graphics providing a workspace. Even back then, you could configure it for light mode, or dark mode. All the colour schemes were equally horrendous, so you chose the least-worst you could, and went from there.

Figure 2 – Borland C++ on MS DOS

Fast forward 25 years and you can download any number of decent IDEs for free, and don’t need to spend the next hour feeding in disk 24 of 30. For C++, I chose Microsoft’s Visual Studio Community Edition. This was to serve me for both my C++ and Python activities and suited my needs well. It’s also the tool I used to render the class diagrams shown in Part 3 of this series.

For about an hour I considered diving into building a GUI version of the Auto120 game. However, recent experience coding a GUI in Android had left me scarred, and my focus was on getting the code to work. So, I decided to save that for a later version, and continued with a console/text version.

As I worked through converting the code from PHP there were a few obstacles that I came up against. Most of these are highlighted in the eight key items mentioned earlier. But there was also the general syntax and expectations of the compiler to consider. My Android experience had dragged me into the 21st century in terms of what contemporary OO programming and IDEs looked like. So, the concept of a ‘smart’ IDE realising that I was attempting to reference a method that needed an ‘include’ and being able to resolve a run-time issue with a click of the mouse, was pleasing to me.

Figure 4 – the Microsoft Visual Studio Community Edition IDE. Much prettier than it’s Borland ancestor.

Pointers and types and dates, oh my

The trickiest thing was working through whether C++ was expecting an Object or variable to be referenced directly, or as a pointer. I’d never quite ‘got’ pointers in my undergraduate studies. I get them slightly more, now, but I don’t really want to.

C++ is more tightly-laced that PHP. It wanted to declare the return type of each Class. I needed to swap my TRUEs and FALSEs for 1s and 0s. I had to declare the size of an array, not just start populating one on a whim. C++ handles destructor classes differently… let’s just say it’s got an itchy trigger finger and has already starting flushing things that you may wish to call on the way out. Still trying to call that method during a destruction event? Nope, she gone.

Generating a time stamp was like going back to driving a stick shift after decades of driving an automatic. You want me to include a library for that? O…K… Integers and strings don’t naturally mix well – PHP was *very* forgiving in that regard – thus requiring a new level of concatenation and parsing.

But the thing that tripped me over time and time again were pointers, particularly when passing them to other Class methods. Trying to get the syntax right between the declaration and the function call-back did my head in. After a few nights of Googling and rewriting code, I realised that the problem lay in a combination of the Engineer (me), and his (my) understanding of the IDE.

Working with the tool, not against it

Modern IDEs try to help you out. You declare and instantiate something in code, and it believes that to be the canonical truth for any subsequent calls or references made to that. However, if you’ve got it wrong to begin with, it goes along with what it believes was your original intent. I realised this when, in frustration, I blew away a set of Class methods that had pointer-based declarations and rebuilt them with direct references. I built a new call in and different Class method that referenced this one, and it worked.

But none of the previous code which I’d written, which looked identical would compile or run.

Why? Because it was looking for a method interface that was from the original structure that had pointer references.  It took walking through the code and re-typing each of those calls – and seeing the IDE pick up the references correctly – to get it to work. Sigh.

Stepping through the selected Hit List items

So – details of some C++ idiosyncrasies that varied my approach when compared to PHP:

  1. No native classes for what I would consider to be ‘basic’ object types – string, array search functions (begin / end / find) and methods for time calculation. The code needed me to include five additional head libraries (string, algorithm, iterator, cstdlib and ctime) to do what I wanted it to do, the way I’d written it.
Figure 5 – Loading up on include libraries in the Game Class
  1. Needing to explicitly allocate space for an array when declaring. C++ wants you to be more disciplined in allocating such memory space. I found this by accident when wondering why my code appeared to be suddenly stopping mid-game. Turned out that I had exhausted the memory allocate for the std::string g_movelog[] array which I didn’t think would go beyond, say, 2000 records. Ah, no – it wanted me to declare the byte size. So, I declared it with a size of 1,000,000 and continued debugging.
Figure 6 – Allocating a chunk of space for the logging string, and creating an array of Players.
  1. Similar issue with declaring arrays of a Class, in this case needing to hold two Player instances in the Game class Player g_players[].  After repeated null object errors, I finally changed the instantiation to read:

          Player g_players[3] = { Player(0), Player(1), Player(2) };
  1. Searching for a string instance within an array was entertaining. This was needed for the method which searches for penultimate or factor Marker locations to avoid moving those pieces. C++ needed to know the start and end of the array reference as well as the location of the piece to avoid. BUT std::find will return a pointer to the space AFTER the last element (as std::end) in the array if it is not found.

    So, the Boolean logic to find an instance of the returned Location of the Player’s piece within the array of x_temp_magic ended up being:

x_test_1 = std::find(std::begin(x_temp_magic_numbers), std::end(x_temp_magic_numbers), x_player.p_pieces[x_temp_value].m_get_location()) != std::end(x_temp_magic_numbers);

In other words, return a true value if you find the location between the beginning and end of array. However, if the find returns the std::end pointer, return a false, because it was not found.

That’s a few hours of my life that I’ll never get back.

Crazy random happenstance

When I finally got it to debug and run, I found a new issue. This is a game of chance and of mental arithmetic. However, after a few single runs I found an issue. The game ran to a valid conclusion in 155 moves. When I reran it, it did the same thing. 155 moves. Huh. Co-incidence? No. Third time, 155. The moves matched play for play. It was algorithmic Groundhog Day.

I’m a big fan of saying “computers only ever do what you tell them to do”. Meaning, the data you feed them, and how the engineer encodes an algorithm. In this case, I realised I was a victim of my own assumptions. As many will understand, ‘random’ numbers generated by a digital algorithm are rarely truly random. They use clever maths to produce an apparently random number, which fools most people into thinking it is, indeed, a number produced by chance.

It isn’t. This is why analogue systems out-perform digital systems in producing truly random numbers. (and even then, thanks to the beautifully written ‘Chaos’ by James Gleick, some analogue/natural patterns are far from random.). What fast-moving digital systems need is a variable seed.

So – the answer seemed simple – add a seed generator in the method ‘g_return_random’ which I’d added as a method to the Game class. So, I did, like so, after including the <random> library:

    srand((unsigned int)time(NULL));

I recompiled and ran, and lo and behold, it worked! A random game. I ran it again, and it was different. Bingo.

But there was an issue. I was raised to believe that C++ was truly fast – epic fast compared to some modern languages, including PHP. So… why was my PHP code, running on a shared hosting platform with so many layers of infrastructure, network and software between it and me, blowing the C++ code out of the water?

Simple and obvious answer. What had changed? Every time the C++ code was generating a random number – which was every move plus often within moves as it decided amongst multiple Pieces to move – it was generating a new random seed based on the timestamp. This, it turns out, was like driving the algorithm with the handbrake on. It worked… but it chewed up a lot of CPU cycles doing it.

So, in the parent calling code (outside of the Game class and in the main() method of the program overall), I added a conditional after each Player’s move:

Figure 7 – Code to generate a new random seed every 250 game moves

(where x_counter is the overarching looper attribute that stops the code running forever; the code terminates cleanly when it reaches 10,000 moves).

So – every 250 loops the random seed would regenerate, including when the code first ran.

After a few weeks I thought… but the average game was 155 moves before the seed was being set. How do we even know it’s getting to this point and changing the seed?

I inserted a debug line in the conditional which read:

   cout << “%%% SEED FLIPPED %%%”;

…and piped the output. The result was obvious-in-retrospect. The modulus of 0 and 250 and is, of course, zero. So, the seed generation was occurring BEFORE the first move of the game. Given the rapidly changing value of ‘time’ (which is returned in milliseconds) it was sufficient to produce a random-enough seed that affected the rest of the game play. The repeat of the seeding at the 250 move mark would mean that any logical loops that had been inadvertently created in the game play would receive a ‘nudge’ that would set them on a new path.

C++ was done and dusted. It was time to move on to Java.

NEXT POST… Embracing the world of Java, with a different IDE and thinking… how hard can this be…?

Design and Code – Part 4 – Implementing ‘Auto120’ in PHP

This is the fourth in a series of blog posts I’ve been working on during COVID isolation. It started with the idea of refreshing my systems design and software engineering skills, and grew in the making of it.

Part 1 describes ‘the problem’. A mathematics game designed to help children understand factors and limits which represents the board game Ludo.

Part 2 takes you through the process I followed to break this problem down to understand the constraints and rules that players follow as a precursor to implementation design.

Part 3 shows how the building blocks for the design of the classes and methods are laid out in preparation for understanding each of the functions and attributes needed to encapsulate the game.

In Part 4 we get down to business… producing the game using the programming language PHP with an object orientated approach.

Get in touch on Twitter at @mr_al if you’d like to chat.


PHP

Available on GitHub at: https://github.com/mr-alistair/ootest-php

Run time version is found at: https://alistairlloyd.com/ootest/php/

My wife runs her own web site design business. (check out Mara Communications if you’re interested… she’s very good!) As a result, PHP is the language I’ve been the ‘most’ exposed to over the last few years. So, it made sense for me to use this to write and test the code following the groundwork of design.

I had dabbled in procedural PHP, mainly making WordPress plugins to add functionality or alter other developers’ plugins over time. This was my first foray into coding in an object orientated method with this language.

I’d cut my teeth of my brother’s 1kb RAM Sinclair ZX81 in the early 1980s, upon which I taught myself BASIC in a relatively constrained yet entertaining technology environment. As a result, and with that raw grounding, I did my PHP development without any fancy IDEs and coded it directly into text files using my web server’s code editor.

This is the coding equivalent of whittling a full chess set out of rough wood pieces on your back porch. It’s slow, a bit messy, and if you don’t watch what you’re doing you’re likely to take head of a Knight off and be left with a messy HTTP 500 error. Nevertheless, it gave me a safe environment to test the integrity of my logic and design, piece at a time.

They say no battle plan survives first contact with the enemy, and that applies to converting an on-paper design to code. Ask any Business Analyst who has faced down an Engineer/Programmer querying the “what ifs…” assumptions and the “we’d never thought of that…” scenarios. You’d think that when you are both the analyst and the engineer that these conversations would take place relatively quickly. Nope. Cognitive bias – particularly in one’s own design – is a terrible thing to wrestle with.

I like PHP. There, I’ve said it. Its grammar is neat, it has well-ordered brackets to contain functions, it is ambivalent to variable declaration, and has beautiful array handling. Sure, it’s not the fastest interpreted language around, and requires it’s own platform (in my case, Apache on Linux, rendering output as HTML), but it provided a safe proving ground for converting the design to working code.

Array Handling

I mentioned the array handling, as this would be highlighted in later version in different languages. For the coding, iterating through arrays to determine if pieces were to be chosen, set aside or targeted required a set of temporary (dummy) array sets to be established which mimicked the live set.

In PHP the easiest way of knocking these out was using ‘unset’ to remove an array element while keeping the rest around it. ‘array_values’ could then be used to populate and tidy a new array with the same contents, and ‘array_rand’ would return a populated element at random. ‘in_array’ would return a Boolean indicating existence of an integer in the array – we didn’t need to know which one it was, just that it existed. Perfect.

Figure 1 – PHP Auto120, extract from Game class, showing use of unset and array_values when determining which Player Marker to move.

Loop de loop, and loose typing

for’ loops in PHP also give you want you ask for. From 1 to less-than-or-equal-to 4? Yep, I can do that. (Remembering, like most languages, the first array element starts at 0 (zero) which I chose to ignore for simplicity… until it came back to bite me later.)

Figure 2 – for loop iterating through the four Markers for a Player and setting a flag if a ‘magic number’ is found.

PHP’s loose typing of variables came in handy when concatenating and writing log strings. Got a mix of strings and integers?  Yep, I can deal with that. Need to force it into a format?  Nah, don’t worry. All good.

Iterative Build

Testing the PHP code happened in sprints. Once the ‘Marker’ and ‘Player’ classes were defined, I coded the ‘Game’ class in stages and progressively added to the game-play as I went. Each scenario threw up different challenges, particularly when ensuring that the logic of what pieces were being targeted and moved were valid. For example, when using ‘array_values’ to copy remaining values to an array, it, of course, compresses values back to the smallest footprint, thus preserving memory.

In this scenario an array of ‘Marker’ objects that is attached to a ‘Player’, containing the locations of the four pieces ( (and including array position 0) may look like so {0,3,24,15,30} but when ‘penultimate’ numbers are knocked out and the array is copied, it presents as {0,3,15}. So, I had to ensure that the copied arrays had a reference to the ‘Marker’ number and location, plus a flag to indicate if it was to be ignored.

‘Marker’ and ‘Player’ were described with public methods, so in the ‘Game’ class I could call the methods directly by referencing the ‘Player’ and the ‘Marker’ methods and objects, such as: 

$g_player[$x_counter]->p_pieces[$x_piece_pointer]->m_get_status()

…to get the playable status of Player “$x_counter“’s Marker number “$p_piece_pointer“.

Similarly, the location of a ‘Marker’ was frequently requested through a similar call:

$g_player[$x_counter]->p_pieces[$x_piece_pointer]->m_get_location()

When fully functional, each game typically has over 100 ‘moves’, so a fair amount of information was written out to the log. I did consider writing some code to display a visual representation of the board as it would appear after the end of each move, but given that I was playing around with a text-only representation I’ll preserve that for Version 2.

What I did find useful was building code into the calling routine to loop through each ‘Player’ and display their ‘Marker’ locations on the board, which was useful in tracking and debugging.

PHP did offer the advantage of including standard HTML colour tags in the output, though. So, I had some fun with colour-coding various status lines, which helped highlight interesting logical choices and twists and turns of the game. In this, you can see how the algorithm is choosing penultimate and factor numbers.

Figure 3 – PHP Auto120 run-time output following a successful game.
Figure 4 – PHP Auto120 run-time output mid-game, showing logging of movements including ‘bumping’ opposition pieces, forfeits for rolling a 1, and successfully reaching Position 120.
Figure 5 – PHP Auto120 run-time output, showing the decision making logging walking through seeking a) a penultimate ‘magic number’, a factor ‘magic number’, and then finding a target opposition piece to hit and bump.

So, I’d moved from concept to design to working code. It ran, it produced consistent results, and much had been discovered along the way which fleshed out the on-paper design.

NEXT POST… C++, dusting off some old knowledge and skills to the same problem using different tools…

Design and Code – Part 3 – Defining the ‘Auto120’ Class and Method Model

This is the third in a series of blog posts I’ve been working on during COVID isolation. It started with the idea of refreshing my systems design and software engineering skills, and grew in the making of it.

Part 1 describes ‘the problem’. A mathematics game designed to help children understand factors and limits which represents the board game Ludo. Part 2 takes you through the process I followed to break this problem down to understand the constraints and rules that players follow as a precursor to implementation design.

In Part 3 the building blocks for the design of the classes and methods are laid out in preparation for understanding each of the functions and attributes needed to encapsulate the game.

Get in touch on Twitter at @mr_al if you’d like to chat.


Implementation – Design

My major at University was a subject stream they called ‘Information Systems’. This provided both a fundamental understanding of what information is and how it is used, but also how it “flows” through any organisation or group of people. Early studies taught the logic and discipline behind ‘functional decomposition’. Or, in simpler terms, breaking a problem down into smaller, component parts until you get to a small enough, modular chunk of logic which can be more readily encapsulated into a coded program.

This is a really useful skill and can be applied to many facets of everyday life and work. It is counter-intuitive to some people who like to dive right in and start ‘cutting code’, but lends itself to more contemporary trends such as epic, story and sprint mapping in agile.

It is also the reason that learn-to-code tools such as Scratch, and groups like code.org do so well in providing children with an introduction to coding – they start by getting the learners to solve logic problems with steps, loops and condition.

So – back to work.

I chose this game as a way of exploring Object Orientated design and programming. I last did this formally around 20 years ago when completing my under-graduate degree (Bach. of Computing, Monash, 2000), where we dabbled mainly in Eiffel and C.  I’d missed catching the Java train by a few years; after I graduated it was to become all the rage, replacing C++ and other stalwarts. Later, languages such as Python as Ruby also came along, and JavaScript matured from being a bit of fun to make crawlers on the bottom of your Mozilla browser, to something more serious and respected.

Again, I sat down with pen and paper and started to work through what a functional breakdown of Auto120 would look like, centered around three main classes: Players, Markers and the Game itself.

Figure 1 – Early pencil and paper breakdown of methods and attributes for the Marker, Game and Player classes
Figure 2 – Working through some of the logical flow for ‘Set C’ which is the method that seeks out ‘magic numbers’ to target. [Plus a bonus explanation of what makes up a cubic centimetre, courtesy of some remote learning math discussions with Miss 11]

Fast forward to defining the classes and methods in an IDE – in this case, Visual Studio 2019 Community Edition, and you get this:

Figure 3 – Class descriptions in table format. Note that there are certain methods and properties that ended up being redundant/deprecated as the code matured, as I realised there were simpler ways of implementing the logic. Shown here is the C++ implementation model, which was the second one built.

This class model is not perfect, but it’s a good start. In summary, the methods and attributes are:

Class – Player

An object describing an actor in the Game. They consist of the following attributes:

  • p_playerid – an integer set to 1 or 2,  identifying each Player
  • p_pieces – an array of  four  Markers , being the playing pieces for that Player

…and the following methods, excluding the eponymous constructor:

  • p_get_playerid – returns the Player’s identification number
  • p_assignpiece – assigns an instance of Marker to the player
  • p_check_game_status – checks to see if all the Player’s Markers have reached the end of the game

Class – Marker

An object describing the pieces (Markers) used by each Player in the Game. They consist of the following attributes:

  • m_location – an integer indicating the Position the piece is on
  • m_owner – [deprecated] an integer indicating which Player the Marker belongs to. [Not used in later versions as it was redundant; we already had a relationship established as you don’t have a Marker without a Player.]

…and the following methods, excluding the eponymous constructor:

  • m_assignowner – [deprecated] assigns the Marker the id of the owning Player [see above]
  • m_calclocation  – returns the potential position of the Marker based on the current die roll value
  • m_get_location – returns the current Position of the Marker
  • m_get_status – returns a flag indicating if the Marker is active
  • m_setlocation – updates the Position of the Marker

Class – Game

The major object encapsulating the methods and attributes for game play. It is driven by an external instantiation (see below).

It consists of the following attributes:

  • g_dievalue – an integer containing the value of the current die roll
  • g_gameover – a flag indicating that the game has concluded
  • g_movecounter – an incremental counter used when logging the game moves
  • g_movelog – an array of strings used to document game moves
  • g_players – an array of two Player instances representing the state of each Player
  • g_playerturn – an integer indicating which Player is currently having their turn
  • m_location –[deprecated, used in Marker instead]
  • m_owner –[deprecated, see above]

…and the following methods:

  • g_detect_clash – Calculates if a Marker which has just been moved has landed on a Position occupied by one or more Opposition Markers. Bumps those Markers back to Position 1 if found.
  • g_dieroll – updates g_dievalue with a random integer between 1 and 6 inclusive
  • g_displaylog – dumps the game log to the standard output screen/document
  • g_find_to_move_in_play – executes part of Scenario Set C, seeking candidate Markers which are on the board (i.e. >1) and choosing one to move
  • g_find_to_move_onto_board – executes second half of Scenario Set D, seeking candidate Markers which have not yet moved into play (i.e. are on Position 1)
  • g_flip_player – hand over the die to the other Player by flipping g_playerturn
  • g_get_playerturn – return the integer value of the current Player
  • g_logmove – write a string to the log array containing a description of the current move or decision commentary
  • g_marker_move – move the selected Marker to the destination Position
  • g_move_onto_board_set_D – driver for Scenario Set D, picking a Marker at random to move
  • g_newgame – called by the constructor to set up Players and their Markers
  • g_player_action – central driving game logic, cycling through the Scenario Sets until one executes successfully
  • g_return_other_player – returns the instance of the Opposition Player (being the Player who’s turn it is not)
  • g_return_player – returns an instance of the current Player
  • g_return_random – returns a random integer between 1 and x inclusive, where x is supplied by the calling method
  • g_target_magic_numbers – used by Scenario Set A and B to forecast Markers which are likely to land on penultimate or factor numbers, and to choose a Marker to move if found
  • g_target_potential _clashes_set_C – driver for Scenario Set C, will forecast Opposition Player Markers that could get knocked out based on the die roll, and the Positions of the current Player’s Markers.

Main Driver (not shown)

The main driver program:

  • Creates an instance of Game
  • Inside of a loop, calls the g_player_action method and the g_flip_player method until g_gameover is flagged
  • Displays the game log

OK. Paperwork is done. Time to cut some code.

NEXT POST… PHP, my tool of choice to fire this baby up and take it out for a run…