Skip to main content

Use examples to make your code easier to understand

Programmers are used to abstract thinking. To program is to generalize: A method is a general specification of what to do during execution. A class is a general specification of objects. A superclass is a generalization of several classes.

Altough our minds are capable of abstract thinking, concrete thinking is much easier, and concrete examples are the foundation for abstractions. For instance, when we were children, our parents didn't try to teach us about cars by explaining to us cars are and what they can do. Instead, they just pointed at a car that was driving by and said ”Look, a car!” When they had done that a number of times, we knew what a car was.

Another example is prejudice. We all have prejudices, because this is the way our minds work. If we have met a few people from Denmark in our lives, and those people were friendly, we ”know” that Danes are friendly. And this works even stronger for negative prejudices.

My point is that we learn by examples. Einstein said that examples is not another way to teach, it is the only way.

As programmers, we are highly skilled in abstract thinking and expressing ourselves in programming languages. But when the code becomes too complex, we try to comprehend it by making examples in our minds of what the code would do in different circumstances. We imagine or write down the values of different variables and what the behavior of different tests and loops will be with those values.

And when it becomes too hard to imagine what is actually going on by reading the abstract code, we use debuggers for help. A debugger is not abstract. It gives a concrete description of what is actually happening at runtime. It gives information on how methods execute in specific instances and which objects exist at a specific moment. This concrete information is so much easier to understand than the abstract code.

Therefore, it's a good idea to design concrete examples of objects and scenarios before implementing the abstract classes.

Unit tests are exactly such examples. They make it easier to understand what happens at runtime. And a well designed unit test is the best way to explain to somebody what the code does. If you ever had to take over somebody else's code, you know how hard it can be to understand it. Where do you start? Unit tests is a good place to start.

So, my suggestion is to think of unit tests as documentation. Write unit tests that are easy to read and that explain the intent of the code.


Anonymous said…
Good post. Unfotunately alot of devs just don't believe in using unit tests they would rather just say 'YAGNI'. Not realizing that a failure to test is a huge source of painful subtle bugs and extra time maintaining the codebase.
Very good point, which I think most developers come to think sooner or later. It's really quite logic, our brains are wired to be pattern recognizers and extrapolators.

If anyone needs an example of this, I usually hand them a copy of the GoF Design Pattern's book as well as Head First Design Patterns. I have yet to meet somebody who prefers the Gof version.
Anonymous said…
Tight deadlines are the problem of why unit tests are never written.
tieTYT said…
I think this is much more applicable to documentation than Unit Tests. Documentation needs examples. I normally find the Getting Started page disproportionately useful to the rest of the documentation. The reason? It's one giant example.
iTsadok said…
I think this post would be better if it had some examples in it. Seriously.
Lars said…
You are absolutely right! Shame on me for breaking my own suggestion!
Marceau Huxley said…
This is a perfect example of why doctests in python are such a useful tool. Not only do they serve to test your code, they also give the api user concrete examples of actually calling the function.

Popular posts from this blog

Database dump with Java

I need to update a database that is created by PHP. The problem is that I am not a PHP coder, but a Java coder, and I need to use some other Java libraries to get the job done. So how can find out exactly which tables to update and how? It would take me weeks to search the PHP code, and I still wouldn't be sure if I got it right.

The first step is to install a clean application on my computer. There is no user data in the database, so if I perform commands like creating a user etc in the web application, I can look at what changed in the database. I'm sure that could be done in MySQL, but I'm not an expert on that either. When the only tool you have is a hammer, everything looks like a nail. So, I'll use Java for that to.

So, I wrote a small Java application that produces exactly the output that I need. It reads metadata from the database to find all tables and columns, lists that metadata and the content of all the rows.

Here it is:import;

World War 2, Rationalism and Agile Development

One of the central values of the Agile Manifesto is Responding to change over following a plan. This doesn't mean that it's not agile to make a plan. You should have a plan, but you should realize the limitations of the plan.

Are there any parallels to this in history?

The Soviet Union had 5-year plans. Stalin was quite succesful in industrializing the rural country in a short span of time. But his methods did not work well in the battlefield. In the 2nd world war, the Soviet suffered severe losses in the beginning.

You can plan how to build and manage a factory, because the complexity is limited. But a war is far more complex. You cannot predict what the enemy is going to do. This doesn't mean that you should go to war without a plan. Far from it, you should plan as much as possible, but be prepared to improvize when something unexpected happens. As Dwight D. Eisenhower, a successful American general in World War 2, said: "Plans are nothing; planning is everything."…

The Pessimistic Programmer

I decided to change the title of this blog to "The Pessimistic Programmer". Why? Am I a depressed person that thinks nothing will work? No, I am an optimist in life. Something good is going to happen today :-) But in programming, something will surely go wrong.

I don't actually view this as pessimism, but as realism. I want to be prepared for the worst that can possibly happen. Hope for the best, prepare for the worst. But my wife explained to me that pessimists always say that they are just being realistic. So, I might as well face it: I am a pessimist.

I think a good programmer needs to be pessimistic; always thinking about what can go wrong and how to prevent it. I don't say that I am a good programmer myself. No, I make far too many mistakes for that. But I have learnt how to manage my mistakes with testing and double checking.

Über-programmers can manage well without being pessimistic. They have total overview of the code and all consequences of changes. But I'…