Rule #1: keep things simple and clear

What's the most important goal for a programmer? Well, the first thing that comes to mind is: to write programs that work. That's a good answer indeed. Programs that work make a lot of people happy: testers, managers, CEOs and eventually customers. I certainly like to use programs that work.

Most programmers would agree with that answer too. Still, I haven't included programmers in the list of the happy people above. The reason is that, as programmers, we should be interested not only in writing programs that work, but also in how those programs work.

The user clicks a button, chooses and opens a document, and that's all the user sees. But we know better. We know that the procedure that opens the document contains several fixes of the last minute, which resulted in a good amount of spaghetti-code and a couple of memory leaks for good. We also know that the very complicated document parsing code has been written by a programmer that has just left the company and no one can put his hands on that. In ten thousands line of code there are only a few comments, of which the one fixme!!! is the most useful.

The user is happy... for now. How long before calls start pouring in the customer support center?

I think a lot of problems in current programs are due to the lack of a clear answer to the initial question: what is the most important goal for a programmer? Or, if we accept the answer given above, how we define "programs that work"? I'll give my answer here, and since it would be easy to start and write a tirade the size of War and Peace on this and related arguments I'll try to keep it short.

For me, software presents two realities: an outer reality and a inner reality. Users are interested only in the outer reality and ask that the software performs correctly and efficiently as promised. Programmers on the other side must take an active role in both realities, making sure that what the user perceives as "the program" is in fact supported by and built upon good code. For industrial software, which is supposed to be written according to well-defined processes and standards of quality, and which is paid for by customers, code has to satisfy two important conditions:

  1. it has to reach its goals in the simplest and cleanest possible way;
  2. it has to communicate clearly and easily what it is doing to satisfy condition #1.

This might seem a little biased toward the inner reality and well, maybe it is, but I feel that most of the processes currently adopted for development are too much oriented to get just a decent appearance and do very little to improve the actual substance. Unfortunately, the connection between cause and effect seems to be lost here. I'm really surprised that companies are willing to spend millions to support buggy software, answer calls by angry customers and send out service packs that take ages to write because programmers cannot understand the code they are supposed to fix.

Of course this is a nightmare for developers as well (which include programmers, testers and documentation writers) but in the many years I've been doing this job I have seen only a few to admit that a large part of the problems is actually caused by bad development practices, i.e. by the developers themselves. And of these, even fewer are willing to do something about it.

I regret this, because in my experience that's where a lot of the fun is. The conditions stated above are not easy to achieve. In fact, they can be very challenging at times but those challenges are interesting and eventually leave you with a very good feeling of satisfaction when you come out the winner.

Now let's assume for a moment that you're already writing great programs. Maybe you're even having fun at that. Maybe not. Anyway... what's next? The answer is simple: communication. Your great code and programming ideas must be communicated and shared with others: the rest of the team, your manager, the internet if possible, even yourself! After a few years even you may find it difficult to understand code that seemed trivial at the time (when you were thinking "Hey, this is so easy I'll never forget it".)

It's important to remember that even in small teams there will be a variety of experiences and skill, so what's easy for you it's not necessarily easy for the guy in the next room. Keeping things simple and clear makes it sure that everyone can understand the code and work on it more easily, with a dramatic impact on quality the final product. Thus communication and related issues (source comments, API documentation, explanation of internals, design) must be considered part of the programming job itself, not something to do only if there is some bit of time left at the end of the project. Because, you know, there won't be any unless you plan for it in advance.

Top: Table of content  |  Previous: Introduction  |  Next: Workday management

Copyright (c) 2003 Alessandro Scotti. All rights reserved.