Postmortem for my First App

Three and a half months ago I started a software development course, to build a new career as a programmer. I’ve also quit playing music. As we come to the start of a new year I’m very happy with these choices and with the prospects ahead.

One of the things I’ve loved for a long time about programming was the culture of sharing knowledge. It directly influenced the tone of this blog. So, while I don’t know whether I’ll continue writing about programming on Drum Chant or make a new blog for it, today I want to try my hand here anyway at a software postmortem.

Following the time-honoured format (which I first saw on gamasutra.org I think, and also used on this blog before), I’ll introduce my project, discuss what went right in the production, what went wrong, and what lessons can be learned about software development.

Introduction

I developed my first app in Java this month. It’s a number-guessing game simulating a lottery draw. I call it Gambler’s Delight. I had previously worked on a similar brief for a group project in school which I enjoyed enormously. So I decided to remake that idea on my own, using a more elegant, manageable design.

The game affords multiple rounds of attempts to win the lottery. In each round the user fills out a lottery ticket of 1-3 lines, where each line is a guess at the 6 random lottery numbers which will be drawn. When the user decides to play their ticket, the application draws the 6 random numbers and tells the player how good their guesses were, awarding fictional cash prizes depending on performance. Finally, the app keeps a record of all the rounds played and displays this when the user requests to end the play session.

So, it’s rather like the Irish National Lottery‘s digital play platform. I didn’t refer to this when designing my game, but my effort converges on the same concepts.

How the pros did it

You may be already seeing some of the design issues I faced:

  • how to make sure the player chooses six unique numbers
  • how to have automatically chosen (“quick pick”) numbers
  • given that some lines are active and ready to play, some not, how to deal with the transitions from inactive to active and back

My own learning goals for the project were to get my head around Java’s Swing library, which provides platform-independent graphical user interface (GUI) widgets, as well as some intermediate programming concepts like interfaces, events, exceptions, and of course the object-oriented programming principles of encapsulation, inheritance and abstraction. (The fourth technique always mentioned with that group, polymorphism, didn’t really come into my app.)

Or, to put it crudely, I wanted to make a simple game but:

  • split it out intelligibly into classes representing real-world objects,
  • use the premade Swing classes more or less as they’re meant to be used, and
  • keep a handle on the structure and proliferation of my code.

What Went Right

A clean GUI: I designed the look of my program in one blast of inspiration, which luckily was then realisable in one of Swing’s layout manager classes, the euphoniously named GridBagLayout.

I decided that each line of 6 numbers would be built as 6 text fields, similar to a licence key or credit card number entry form. And I was able to have all necessary user actions available on this one, small window, in a layout based on the number 3.

The concept ((also demonstrating the importance of having appropriate stationery on hand 🙂 )
My GUI in action

Encapsulation: as you can see in the source code, I split the functionality of my game into 9 classes and and an interface. Many of these are satisfactorily neat and conceptually self-contained. Even the bigger ones use some basic principles to hide their data, i.e. private variables. Also, I followed the correct convention for passing arrays – copying their contents into a new array before passing that – to avoid giving the requesting class access to a private array in cases where this matters, e.g. the LottoTicket’s getResults() method.

Keeping control of my code: I was pleased that by the end of this project, I still knew clearly what everything did and where to look for any particular functionality. I could skim my code and know what I was looking at thanks to nice variable and method names, whitespace and my reasonably clear class structure. I’m an ultra verbal thinker so writing lines like “history.updateWith(ticket.getResults());” that do what they sound like they do in approximately readable English, pleases me no end.

Use of Java classes: the built-in classes I used – probably around 12 or so – were rewarding to study and build around. Of course they are, they’re made by top people! The experience of using things like Swing’s InputVerifier or Container classes, say, is of initial simplicity giving way to great depth and flexibility. The big but logical inheritance hierarchies of these components are inspiring. I’d love to make something someday as worked-out and usable as these. The only downside of my plug-and-play approach is that I ended up using a good few classes quite superficially. I can see how later it’d be all about digging down deeper and overriding parts of fundamental classes to put my desired custom behaviours in more unified containers that match their purpose more elegantly.

Use of events: I used a good few of Java’s event types and wrote one of my own, so now I have at least some insight into event-driven programming.

Bullet-proof UX and validation: I’m proud of this achievement even though conceptually, behind the scenes, it could’ve been cleaner. My interface instantaneously reacts to invalid input with an appropriate error message and an updated count of how many lines are ready to be played. The only exception is, I allow the user to leave fields blank for smoother navigation. It’s impossible to leave an unplayable input in a field, and impossible to play a line that doesn’t validate correctly (e.g. has blanks). There are two subtleties to this. First, I had to use multiple kinds of events to make sure and cover all interactions: DocumentEvents, FocusEvents, ActionEvents… and then pass the appropriate EventListener classes back and forth when building all the objects (lines, fields, verifiers) in my game. That’s overly complex for sure. On the plus side, I had to take care of weird player behaviour like going back and deleting numbers from previously finished lines. That involves some slightly tedious code but the result is robust.

Minimising hardcoding: I kept crucial gameplay variables in a separate LottoRules class and made sure that they only need to be changed once to correctly change the game’s behaviour. However, I chickened out of following this to its proper conclusion of allowing customisable line lengths and number of lines per ticket – the game logic can handle this, but the user interface wouldn’t dynamically adjust.

What Went Wrong

Having no target audience: the game was inspired by a brief for a college project. It doesn’t fulfill any real user’s needs and therefore there’s no point continuing to develop it. Honing in on excellent design becomes arbitrary in this situation. For my next project I’ll come up with something that I, and hopefully many people, definitely want.

Insufficient use of exceptions and defensive programming tactics: changes in one part of the code could easily cause crashes or undetermined behaviour because I don’t check the validity of values or handle wrong values (apart from the user input discussed above). That said, I think I’m right to move on without polishing this more.

Hardcoding: this point also contravenes good programming practice. The UI I made isn’t adaptable to different line lengths/amounts, and has some per-pixel hardcoding. But here I was coming up against the fact that system-independent GUI design is hard. Java’s Swing layout managers are pretty flexible and wide-ranging, but with that comes a lack of predictability and precision. I think next time I might try a different GUI technology – AWT, or something web-based – just to keep learning new stuff.

Lack of reusability: although I made one class explicitly for future use, (TextNiceties which deals with plurals and counting words) I mostly failed at designing for reuse which is, so my software engineering teacher says, the holy grail. Partly this is due to the trivial but finicky task: much of what I wrote is for the necessities of this particular game. Then there was the spreading of GUI code throughout my classes, which I’ll discuss below, but which obviously makes my code specific to one task.

Refactoring is hard: “restructuring existing computer code—changing the factoring—without changing its external behavior” as Wikipedia defines it, was challenging. I already had a working prototype at the start of this project, from my school group work. Unfortunately I tended to unthinkingly take elements of the previous design into my new one. And I also assumed that problems were already solved without noticing that with changed design assumptions, my previous techniques were now invalid. So, I made two failed attempts at restructuring my GUI code before settling on a pattern of passing a window (JFrame) object into my various classes so they could paint themselves onto it.

Deciding what object should have what responsibilities: I had the concept of an overarching “app” creating a lotto “ticket” containing “lines” which each contained number “fields”. Reasonable enough, but the question of which object should know about which other objects was hard! This applied to the UI creation, the validation, and the game state changes… I have tons to learn here.

Over-engineered interface: I allowed the user to invalidate a completed line of numbers by clearing text fields. This adds nothing, it’s merely a standard text input convention. I think an excellent design would intentionally limit such possibilities in the interests of clarity and simplicity. I note that the Irish National Lottery interface:

  • uses a graphical grid of numbers that are either selected by a single left click, eliminating duplicates automatically
  • doesn’t allow deselection (deletion) of numbers, so lines are simply always valid once completed – and bright colours are used to indicate the change to valid
  • therefore never has e.g. the first line invalid while subsequent ones are playable, an edge case I had to write a fair bit of overly-involved code to deal with

Conclusion

I’ll stop there. That’s a lot of chat about a learning project, but hey I’m proud of it and I sank a few days into it. Nice one if you read through it all and perhaps I’ll be back soon with a cooler project. A friend of mine gave me the idea of doing something that queries a web API, and I also think I want to do something with non-trivial calculations (maybe some geometry/graphics) and file handling.

*EDIT* Oh, one last addition – I think I know now what the solution is for organising the line, field and ticket objects and their drawing code. Sticking closer to the paradigm from John P. Russell’s excellent beginners Java book, I would go back to having each major element subclass a Swing component such as a JPanel, and draw itself in its constructor. And, I would structure the lines like a group of radio buttons: first a LottoLine would be created, and it would be passed into the constructor of all its LottoFields.

Ah well, there’s always more improvements to make. Still happy to draw a line under this project, cause it works and the code is readable.