This week, we’ve had a fifteen year old student visiting us on a work experience placement. He spent a while with the systems engineers, the network manager and the web designer, and then yesterday it was finally time for him to spend a few hours with me and Lisa. It turned out that his ultimate goal was to become a programmer, and so I was given my first - but, I hope, not my last! - chance to help someone just starting out on the career that I’ve chosen. This was clearly a golden opportunity to impart some pearls of wisdom, and after a little thought I settled on three. They’re not an entirely orthogonal set but it seems to me that they’re pretty good advice for a neophyte software engineer:
-
Source code is a way to communicate with people, not machines.
The compiler will happily understand many more programs than people will. While programming, you should always approach structuring programs and their source code as a means of communicating ideas to other people. Sometimes those other people will be colleagues and sometimes they will be your future selves. If they can’t understand your program then much of its potential value will be lost as it will be much more difficult (or even impossible) to maintain and extend. This attitude should inform everything from the overall architecture to the choice of variable names. Most especially, you should write comments that explain the intention of the code and not merely how it does what it does. -
Every part of a system should have a clearly defined responsibility.
Programs are easier to understand when each module, class, method, or function has a very clear and coherent purpose, fulfils that purpose, and does nothing extraneous. The system should decompose naturally into components. (If you have trouble giving a method or a class a snappy name, this is probably evidence that it’s conceptually confused.) As far as possible, separate mechanism and policy. Furthermore, separate the logical structure of a user interface from its presentation if possible. (For example, in dynamic web interface design you can separate the interface into Javascript which describes actions, HTML which describes structure, and CSS which describes presentation. These three things should no be mixed up in the same file.) This not only makes the system easier to understand - see point (1) - but also makes it possible for many people to bring their diverse talents to bear on parts of the design and implementation. -
Each fact should be recorded only once.
This idea, known in the world of databases as the principle of normalisation, should be applied as widely as possible. Your code should not contain multiple blocks of identical - or very similar - code. You should not have to update your documentation in parallel with your comments. You shouldn’t write classes whose attributes mirror the fields of database tables. Not only are such denormalisations wasteful of your time but they also introduce a very real danger that the instances could drift out of synchronisation. Don’t be afraid of abstraction. Don’t shy away from inheritance. Generate documentation automatically from comments. Generate database access code automatically from your schema. Elegance, simplicity and frugality are all virtues. Drudgery is not.
If you had to distill all of your insights into your chosen field into three such pearls, what would they be?
Update (18/7/2006): Over at my Livejournal, people have started to contribute advice:
Leave a comment