Code documentation

Nope, I did better. My simulator has got some documentation.

I'm not a big fan of lengthy and hefty technical documents. When I worked as application developer, I came across those 100-and-more page documents that explained in writing what a single function or method was supposed to do, the way was supposed to work and how it fitted in the overall project structure. After a couple of months, those documents used to become outdated, unreliable and misleading. Basically, they were a waste of money and time for anybody - I'd rather go for no documentations than a misleading document.

But hey, that doesn't mean documentation is all bad. What if I had very light documentation, describing what the inputs and outputs are, fully embedded in the code, easy to generate and update? That is, some sort of way to auto-documenting the code I write.

I must be stating the obvious, but that's exactly what Javadoc does, with some limitations. Javadoc homepage on the Oracle site fully describes Javadoc main features, functionality and limitation, so I won't go much into details. 

I focused my documentation on the interfaces, interface methods and classes definition. Javadoc documentation is generated within the IDE, which provides tools and resources to write documentation quickly. I rarely document how my Java methods work - I often keep code implementations easy to read by using good formatting templates and one-shot variables, since I believe good code snippets document themselves. Eclipse helps keep documentation up-to-date by changing Javadoc comments during code refactoring, avoiding outdated documentation.

For high level documentation, I use UML2 tool for Eclipse. UML2 generates maps of class and interface dependencies, giving me an overview of the overarching project and helping me spot wrong dependencies (dependencies that don't follow the IoC model) or opportunities for optimisation.

Dependency injection by Spring

In a previous post I stated that classes must implement interfaces, and interaction between classes will only occur through their respective interfaces. The idea behind this decision is quite simple: in order to facilitate reuse and testing principles, Java classes should be as independent as possible from other classes. Classes that have no hard dependencies - they don't reference any specific class instance - can be used and tested in isolation, primarily through mocking strategies. This program pattern has been extensively defined and comes under the name of dependency injection, or inversion of control (IoC).

Spring is a framework that provides developers with a comprehensive list of tools for the implementation of dependency injection in Java projects. Spring is massive. Spring will make coffee, if properly instructed, and that's the main reason why I adopted Spring. Oh, and also because I used Spring when I was at uni and other options (Guice, Pico) are not very popular, yet. Must be a reason why, after 8 years since I left uni, Spring is still that popular.

I'll be using Spring 3.1.0 libraries and a bunch of dependency libraries such as commons-logging and spring-security. A full list of libraries used in this project is available under the /lib/ folder.

An iterative and incremental design approach

I spent few weeks thinking about the best design/development strategy for this project. Considering the scope of the project and the high number of functionality, I decided to go for an iterative and incremental approach.

As James Shore writes in this article, "start by creating the simplest design that could possibly work, incrementally add to it as the needs of the software evolve, and continuously improve the design by reflecting on its strengths and weaknesses". The idea behind this approach is very simple: I find hard to define precisely all the different cases, scenarios and rules of my application. Better to split the job in different iterations, each of them targeting a specific case or scenario. Basically, I would rather have a simple system perfectly working, than a complex system not working at all.

A few acronyms. This approach will blend with behaviour driven development (BDD), leveraging object-oriented (OOP) and, to some extent,  aspect-oriented (AOP) programming. I use BDD because I find quite effective the idea of define units of software in terms of desired behavior of the unit through unit tests. BDD is naturally implemented by OOP, such as Java, a programming language I'm very familiar with. AOP will be limited to certain features, such as logging or reporting, in order to increase class modularity.

In order to facilitate the development of this project, I will adopt some basic principles:

1. Classes must implement interfaces, and interaction between classes will only occur through their respective interfaces.
2. Unit tests will use mock strategies to mock the implementation of any other interface used by the tested method. Test classes will be created along with the interface creation.
3. Aspect-oriented programming will increase modularity of my classes. The idea here is to have different classes for different jobs, avoiding cross-wires as much as possible.

Be collaborative

As much as I would love to, I can't do everything by myself; I can start this project by my own, but then I would need some help from the community. That's the main reason why I will use a web-based hosting service for software development, GitHub, to share the code of my simulator and foster collaboration between developers. On top of that, hosting services like GitHub offer file backup and revision control, both very useful features in every software project.

GitHub, as the name suggests, is a hosting service that use the Git revision control system. The reason why I'm using a DVCS rather than a standard client/server version control (like SVN) is more an experiment. In the past, I've always used SourceForge and SVN as my hosting service. I'm now looking forward to testing a distributed model and take full advantage of local repos.

Finally, I adopted GitHub because of its integration level with other platforms and applications. I develop software applications using Eclipse (spoil!), a well-known IDE for Mac, Windows, Linux. Eclipse / GitHub integration is achieved quite well via EGit, but when I'm on my iPad (see this post - sorry, only Italian), what IDE can I use? I tried different iPad apps, but none of them were any good. I eventually bumped into Orion, a web IDE developed by the Eclipse guys. Orion allows cloning GitHub repos and develop applications through a web-browser. I'm still a bit sceptic about the practicality of this service, but I suppose I can give it a go.

Ah, almost forgot to mention. My repos are:

• blackjack-simulator
• blackjack-simulator-test

So far, I only uploaded all the files in GitHub. There is no readme, no branching strategy or any other cool stuff. Stay tuned!

Some (non-obvious) rules

Isn't blackjack the game that you win when you have a 21? Just make a function that randomly gives you a few numbers, and whoever gets to 21 wins. Project sorted!

Ah, if only it could be that easy. Before cracking on with design, I must have a better insight of what I'm going to design, which means I must increase my domain knowledge in the blackjack game. Lucky we live in the 21st century, Internet can give all the answers to my questions.

I'm most definitely not going to write a post on all the different blackjack rules. As my old professor used to say, this would be a "minestra riscaldata" - "same old story". Here is the list of websites I had a look before starting with the design:

• Blackjack - Wikipedia
• Blackjack: Rules of the Game
• Rules of Blackjack or 21

As you can imagine, blackjack game has got tons of rules, variations and strategies. My simulator will be flexible enough to accommodate all these combinations. Whatever software I'm going to write, it won't require recompiling the whole application each time a blackjack rule is tested, a new variation is simulated or a new strategy is introduced.

Goal and strategy

As I mentioned in the introductory post, the main idea behind this project is to find the "perfect" blackjack game strategy. The perfect game strategy is a strategy that maximises the chance of winning one or more blackjack games within the game's rules.

In order to achieve this goal, I will create a framework to compare different blackjack game strategies. This framework will be a blackjack simulator, an application software able to simulate a blackjack game according to a set of casino rules and player strategies. During the course of the game, this application will collect data for statistical purpose. The simulator will run enough games in order to collect statistical-relevant data, and will organise those data for analysis once the simulation is completed.

The simulator will be flexible enough in terms of configuration settings. Simulator users will be able to change the configuration settings, such as game rules or player strategies, without being asked to re-compile the application.

The secondary goal of this project is to keep myself up-to-date with new technology. I will always try to experiment new frameworks, libraries or techniques, or simply adopt patterns never used before.

That's it. I tried to keep the goal and strategy statements pretty simple and straight forward. At any point in the project, I will be able to review the work done so far against the original goal and strategy and make sure I'm on track.

Oh, just one more thing: I didn't mention any deadline. I haven't got a deadline for this project. We are told by purists that one of the characteristics of a project is that there is a definite start and end-date. Well, my project hasn't got a deadline. This project has got a start date - when I initially thought about the simulator, some time last year - but no end date. This project will be completed when the first goal is achieved.

Let's kick off with some design now!

Introduction

Blackjack simulator blog is all about the ancient science of sword making. Ah ah. I'm joking, of course. My name is Luca Cacchiani, I would like to introduce my blackjack simulator, spread it to the world and eventually become millionaire.

A little bit about myself. Like almost every superhero, I work for a respectable company during the day - a digital agency based in the City of London. I enjoy good pub food for lunch and jogging along river in the evening. But at night time, when I take my shirt and trousers off and put my hoody and sweatpants on, I become a java developer. I do understand it's not as cool as being Batman or Superman, but hey, I'm still a geek, even in my 30. And unlike Batman or Superman, my identity is fully disclosed on my cv, my blog (Italian), my facebook / twitter / linkedin / google+ profile. It's hard to keep secrets nowadays!

Rolling back to the purpose of this blog. The goal of the blackjack simulator that I lazily developed is to compare the results of different blackjack strategies through a java simulator. The goal of this blog is to document all the work done so far, discuss future development, gather idea and possibly build a community of people interested in the same subject.

If you happy to participate in the discussions, please use the appropriate comment boxes at the end of each and every blog post. Feedback is always appreciated!