This is a programming tutorial.

This is a fully functional implementation of the game of mahjong, with competitive computer players, made for two reasons. The first being that I like mahjong and I wanted to be able to play it on a computer without having to install any software for that, and the second being that it's a great example by which to explain how to go about writing software that isn't trivial. We've all seen tutorials for writing a "todo app", or "a single web page", but those aren't things you'd actually want to write if you were to make something: they're simple toy exercises to show off "how easily you can make something". The problem is that tutorials like this gloss over the fact that actually making something rather than doing a simple exercise isn't easy. Writing software is hard.

And because it's hard, being told that it's easy also makes it really easy to forget to plan for hardship: once you find something you actually want to do, you soon discover that just following the same methodology of that easy, toy implementation makes you run into all kinds of obstacles, and if you're not careful, or you don't have someone to help you get on track, that thing you wanted to make just grinds to a halt before it gets abandoned altogether. Tutorials don't teach you how to plan for work you know is going to take more than a few days to get done, so what if there was a tutorial that did? A tutorial that covered the space between toy problems and product programming as a day job? That's where this comes in.

And not just because of the amount of code involved, it's also because you need to understand how much you can break up the work, when to recognise you're going too many different things, and when to abandon something that just doens't seem to want to work so that you can try a different approach. Programming is hard, you're going to fail at some point, and it would be super nice if there was a tutorial that didn't just tell you want to do, but also told you what failure looks like, so you can spot it, and maybe even avoid it.

The game you can play, above, took about two months to write in my spare time, and I'm going to assume you'll be doing the same, because you probably already have a job, or you're attending school, and you don't have the luxury of spending 16 hours a day on personal projects. So: if you want to learn to program something non-trivial, and you understand that this means you'll probably be working on it for a couple of weeks, or even a month or two: this might just be the tutorial for you.

Of course, if you just came here to play mahjong, then as an added bonus, you can! Keep reading for an explanation of how mahjong works, and specifically which rule set and scoring system this particular implementation of mahjong supports.