Software development…

Today, I want to talk about designing software. Basically, I want to explore my principle of items-transactions-contracts (ITC) that I’ve discussed before. But let’s look back on those first.

An item is just that. It’s something that you have to work with. It can be a person, or it can be a currency. Maybe it’s a product or just a description of a product. Whatever it is, it’s something that has data that you need to use. Items can be containers for other items, thus items have children and one parent. Like a box of matches that has two matches. Or a person who is part of a household.

Transactions will handle amounts and describe movements of items. Basically, a transaction is nothing more than a message saying that an x amount of item A is moved from item B to item C. A could be a bike that is moved from the shop to its new owner. Or it’s a crate that’s moved from shore to a boat. Or it’s an amount in Euro’s that’s deposited in your bank account from your employer. Transactions allow you to move around data, but also to create or remove items from your system by moving them from to towards the void. (The null container, meaning either recipient or sender is null.) Transactions are also related to time, since a transaction will happen at a specific moment.

Contracts are used to group transactions together. Most transactions are part of a collection of transactions that are related to one another for a special purpose. For example, your savings account will give interest but to get that interest, you first need to put money in your account, and wait for a while. You do a transaction and your bank will follow-up with transactions. Another example is when you send a package overseas. First you deliver the package to the post office, which will give you a receipt back, confirming your delivery. The post office will then move the package around by truck to the harbor, then by boat to cross the sea to the next harbor where a truck will pick it up again to bring it to the post office nearest to the delivery address. And then a mailman will deliver the package. And in every step the post office will send transactions back to keep track of the package so it won’t get lost.

Each of these are governed by templates. You can have templates describing specific types of items or specific types of transactions. You would generally also use templates for contracts. Most object-oriented developers are already familiar with templates and refer to them as “classes” or “object types”. But if you create dynamic objects, you would have to deal with dynamic templates to describe the layout of the data.

When you look at your design, you should try to see if you can divide your data in these four groups: Items, Transactions, Contracts and templates. You will notice that many systems won’t match this pattern. You will also notice that projects that don’t match this pattern might have some limitations on what you can change about them without doing a lot of re-factoring. So, does this pattern work for real-world solutions? Well, let’s set up a design.

The case: a movie theater wants a completely new system to do its administration. So the first step would be to find the items that you would need. Of course, you’d be dealing with persons, with movies, with merchandise and snacks and soft-drinks and of course with tickets. But you would also have to work with chairs, since people want to sit while watching the movie. And the theater hall where you will play the movie. Maybe you also want to keep track of the equipment. But that latter thing isn’t very important. One more thing that is important is money. Money is a strange item but you still need to keep track of your money…

Well, the persons can be divided into multiple groups. You have employees who you need to pay and who collect tips from visitors. They might also receive commission from the sales of snacks and drinks. You will need a lot of data about your employees.

You would also have visitors, but in general a simple headcount would be enough. You could have special visitors like movie directors or actors who visit your theater so your system might want to keep track of some special visitors. (It would also allow visitors to subscribe to your theater.)

And then the contacts that you’re in business with. You need to buy the movie rights, buy the food and drinks from distributors, maintain the address of your accountant and other important persons and maybe even keep a list of important actors and directors whose movies you want to show. This would be a generic address book, but you might want to link these to specific items in your system through transactions. If you use Microsoft Outlook, these would be in your Outlook Contacts, but your system could link to it and e.g. send an order when your stock runs out of soda.

So, we have a list of item templates already, and it’s already growing fast. The next step would be determining the transaction and contract templates and link them to the item templates. For example, your employees work for you so you have contracts with them. For every specific amount of time they give you, you will give them a specific amount of money. This is their salary. Also, the commission means that for every amount of products that they sell, they will receive a small percentage of the profits on those items. So if they sell a soda for 2 Euro’s, they might receive 4 Euro-cents in commission.

Next the visitors, who also have a contract with you. They buy a ticket which will give them access to a specific hall at a specific time for a specific duration. In the most complex situation, you have a transaction for the payment, one for giving the ticket and one for the visitor to move from the void to a specific chair in your hall. And another move of the visitor from the chair back to the void when the movie is over.

And then you have the transactions with your distributors and suppliers. You need to buy movie rights and maybe you have a specific contract with your distributor which provides you with 12 movies per year for a fixed price. So one money transaction from you to the distributor and 12 transactions from the distributor to you. Your suppliers will also have plenty of transactions. You pay them for a crate full soda drinks, which they deliver. But they will also pay you back for the empty packaging, which would be the crate and the empty bottles.

To put this all in a design, you would at least need three tables. One for items, one for transactions and one for contracts. You would also need a place to keep the templates, but those could be just part of your code. There’s no need to make things more complex if you don’t need the extra flexibility.

The tables should not be simple database tables. You need a more object-oriented database system. In Visual Studio you have such an option by using the entity framework. This framework will allow you to add inheritance to your tables so the Persons table would inherit from the Items table. Thus, a person would still be an item, but an item isn’t a person. By using inheritance you could set up a simple, generic system for all the things I’ve described above and once you’re done, you have a great engine for your administration project. You can easily expand it with more functionality and depending on how you’ve set it up the migration to newer versions would be very simple. The entity framework will give you a powerful data layer and your next step would be to build a business layer and GUI for this project.

When you follow the ITC principle, then any developer should have no problems recognizing the purpose of any data item in the project. You might replace your complete development team with a new team, and the new team would easily see the layout of your datamodel. No complex documentation would be required since the hierarchy of your data tables would give more than enough information already. Just be aware that no one should step away from this principle or else your project becomes more complex again…

A generic data model.

A lot of developers will work on software that is doing some administrative tasks. And each and every developer will have to come up with a data model (or object model) which would contain everything they need. And most of the time, they will choose a model that solves their own specific situation but which is hard to change if something new is required. And that’s because developers are too busy looking for details and thus they won’t see the general image.

The general image is that you basically deal with just four kinds of data. No matter if you’re building a web-shop, in-house banking solution, patient record administration or complex financial applications, you always have just four kinds of data: items, relations, transactions and contracts. So let’s take a closer look at these data entities…

Items

Items are just what the name suggests. It’s something physical in general, although electronic data and other things could also be considered items. Persons are items. A complete household is an item. Companies are items, so are products. Animals are items. Phones are items. And most importantly, money is an item. Items are the things you’re going to administer.

Items can be unique. For example, a person is unique. But when you just keep track of the number of employees without looking at the individual, then you basically have an infinite amount. The same with money since each coin is unique, but your bank account can technically hold quite a lot of those coins. Or none at all. Basically, you could subdivide items into two parts: singular and plural items. But this is just a special property for the Item entity. You could add a field called “IsPlural” to the entity or create two child classes that you derive from the Item object. (SingularItem and PluralItem.)

Relations

Relationships are what connects two items with one another. And there can be quite a lot of relations. A person has a father and mother and most have four grandparents, although some might not be alive anymore. Many people also have children. Other relationships could be a bank account that’s owned by a person, a certain amount of money in this bank account and you could also think of the relationships between an employee and his employer.

Relationships can be very complex but keep in mind that there are just two sides on any relationship. examples: I have 10 dollars. Mary-Anne works for McDonalds. This envelope contains a letter. By keeping it simple, the data model stays simple, although you might need multiple relationships to describe certain situation, like employment, your bank account or perhaps even your mortgage.

Contract

This is where you will need a contract, although that might sound a bit of strange when talking about family relations. Basically, it’s just something that will connect items to other items through relations. And, often enough, the word matches the collection of relations just fine. For example, when you work for an employer you will deal with several different relations. First of all, the direct relation between employer and employee. But also the relations between employee and salary, plus employer to salary. But also you and your colleagues will be related, although that would be implied because the generic relation between employees and employer. And of course there’s a relation between you and the office where you work, you and the desk that you work on, or the computer that you use at work. There are plenty of relations that you can define but in general, stick to just those relations that matter.

Contracts not only maintain relationships but in general will contain some logic to change those relations or that are related to specific actions that need to be taken to maintain the relationship.

Transactions

However, there’s one more thing we have to be aware of. And that’s time. And time changes things. People might have a divorce, lose their job or easier: spend money. In the employment example, there are many transactions to think of. Salary happens to be a regular transaction where the employee receives an amount of money. The employer will have to spend this, and the tax office will also have a small claim on the amount the employer pays out. Again, just focus on the transactions that are considered important within your solution.

In general, there are two kinds of transactions. One that creates a relationship and one that breaks it. But a transaction also occurs on a certain moment in time, be it the past or the future. And often the connection between items will require multiple transaction to describe a complete situation. We have the employer who loses a certain amount to pay salaries. We have the tax office (and other offices) that will receive money related to the salary. And the employee will receive an amount related to the salary. And these relations are linked to a contract. The same contract that defined the relations between the items.

Transactions don’t have to involve money, although they often do. But if you buy a steak at the local butcher, you not only have two transactions for you losing money and the butcher earning money (who will lose some again for VAT) but there’s also the transaction of the butcher losing a steak and you gaining a steak.

Conclusion

When you’re doing the financial administration for a company, you will deal automatically with items, contracts, relations and transaction, even though you might not realize it. When you’re building software for a library to keep track of book loans, you also have a similar setup, where transactions determine who is lending which book and when it’s expected to be returned.

Even when you’re baking a cake, you could apply this data model. All ingredients and utensils would be items. The recipe would be the contract. The relations are basically simple since the item is either an ingredient of the final cake, it it is used to bake the cake. And the transactions are just describing how you should put the ingredients into a bowl, mix them, fill the pan, put the pan in the oven, remove it from the oven, remove the cake from the pan, add ingredients to give cake some color and additional taste and then use a knife to slice the cake and eat it. Each of those steps should be taken at a specific moment in time and the transactions will specify when it’s time.

It is a strange example but it shows how flexible the data model actually is. So look at your own projects and see if you can recognize these entities that I’ve just described. Most software will have entities with multiple functions, where e.g. a Person record contains a link to parent records or child records. Or links to employer, bank accounts or whatever else. In general, such constructions would severely limit your options. And although a person won’t have more than two parents in general, a person could have two or more employers. So sad if your system can only handle one employer…

And while you don’t have to use this data model for your own solution, altering your data model to match this one will improve the flexibility of your whole design.

First! A new project.

I have been working on a simple project to maintain a lot of data for the game Grepolis which I happen to like. I am just in one world, on the Dutch version, which is called Nu. And while playing this game is fun, I’ve decided to combine this kind of fun with another kind of fun: software development.

As it turns out, Grepolis provides a web API which allows everyone to collect data from every world within the game. So by using this API to import data to my database, and then use this database to feed it to my websites and other application, I can make some good use of this all. And it became quite practical.

But a fun project can grow to something bigger. So I decided to share my code at Google Code but this needs the code to be cleaned up a lot. This is supposed to show the best of my skills and if it looks bad, my skills are bad. I don’t want my skills to be bad. So by sharing the code I also hope to receive some feedback. Feedback is good. It’s nice to hear it looks nice. It’s even nicer when other people will show me the flaws in my work.

For now, the project has one owner, who will do all the hard work. This might change in the future, when the code has matured a lot and enough volunteers are available to help me with the code and the additional content. It doesn’t do much. The web site won’t even compile at this moment because I’ve changed too much in the database and business layers. I will be working on that, but first I need to get the datamodel just right, then make sure I have a working business layer. The most important part of this project isn’t displaying the data, it’s importing the data. And that’s not as easy as it appears.

UPDATE:

Since I quit Grepolis a while ago, I also stopped maintaining the code. It has been removed from Google Code and my copy of the code is lost in the catacombs of my enormous backup archive. For those who are still interested, I will try to find a copy of the code to put online.