May 22, 2011

Engineering principles for web applications

Since I work as a web developer, I have noticed that basic engineering principles are not always being consistently applied to web applications design, architecture and development. I am talking about modularity, black-box design, documentation and quality assurance, among others.


It may seem trivial for small-medium web sites and the 80% of the web interfaces on the net. However, this matter becomes crucial for medium-big applications with complex interfaces and functionality. A good application architecture consists also on a good modularity design:

  • All functions related should become a module.
  • Modules must have a low coupling (high isolation), so that if a bug occurs, it affects only one module and some neighbors at most.
  • The interfaces between the modules should be as small as possible.
  • The interchange of messages through these interfaces must be also minimized.

A good modular design produces an architecture than is extendable, maintainable, adaptable and reusable, thus allowing to reach further goals. A lock of modular design just produces a bunch of unsustainable “spaghetti code”, eventually.

Black boxes

Another concept on the line of thought of modular design is black boxes. Engineering likes black boxes, they are useful, modular, isolated, independent, and provide a smart set of independent pieces that abstract their internal logic from outside.

Basically, a black box is an element whose implementation is unknown to us, but which is well-documented and produces an expected output, given a known input. This implies also abstraction and encapsulation: no inner property should be accessed or changed from outside the box, nothing from other parts of the application should affect the internal structure or functionality, and an I/O interface should be created so that this black box is only used as it was designed to. It is not about “protecting” the classes from malicious uses. It is to avoid ourselves incorrectly using these classes when their implementation is no longer in mind after several months of their creation. It is easy to forget a tree on a big, big, forest.

The beauty of this approach is that test plans are easier to design, code is written faster and programmers can rely on every piece of the application doing exactly what it is meant to. Black boxes become the cornerstone on which big applications’ architecture must lean.


I’ve heard a lot of excuses from all kind of developers not to write a proper documentation. I, too, have used it sometimes, in darker times when I was learning how things should be done. That’s why I spot them easily:

  • Release dates are tight and I barely can finish functionality.
  • The code is self-explanatory.
  • I will write it when I’m finished with this.
  • I just don’t have the time to write documentation.

Unfortunately, I have to say there is no excuse not to write documentation; moreover, it should be done first, before start writing a line of code: comment out what the function you are coding is to do, add a few lines explaining the process to get it, and don’t hesitate to add as many side information as you want. I know that pride about ‘not writing silly comments every good programmer should not need to understand the code’, and it is wrong.

Programmers are not magicians, they don’t read minds! Everyone has different coding styles, skills and languages, and it is not obvious for one to understand what a piece of code should do, just reading the code. It may be clear what it does but that might be wrong and the source of a bug being tracked for hours.

Not only have I seen many people spend many ours of their valuable time tracking ‘esoteric’ bugs through unreadable, unbearable, non-documented code, I’ve lost myself months of my short life figuring out the architecture and purpose of entire applications just because the last programmer “didn’t have the time to write documentation”.

Can you imagine the loss for the company? Huge, indeed. Finally documentation has its toll paid back, one way or another. I’d rather like not to waste my time, don’t you?

Quality assurance

Another almost forgotten issue regarding web development is quality assurance. Deadlines are tight, developers are stressed, the application looks nice, so… who cares if a variable is missing or a method of a class goes nuts? It is unlikely to happen, we all have tested functionality and everything works.

Well, that’s again a wrong argument. Experience says that the cost of solving a bug is more than ten times the amount of resources needed to prevent it from the beginning. Think of it:

  1. A customer has the application exploding when she tries to use a functionality we hadn’t previously tested.
  2. She calls customer support, this produces several messages going back and forth from one part to another until the bug description reaches the development team.
  3. A developer, usually not the one that wrote the code, has to spend hours deciphering it (remember about documentation?), reproducing the bug, understanding the underlying problem and fixing it. If this code is more than a few months old, the effort to reload it on a mental representation is several times bigger than if the bug was fixed on the initial development cycle.
  4. A new version / patch has to be released and delivered to one or all clients, producing service temporary interruptions.
  5. Excuses, apologies, unhappy costumers, official communications explaining how to fix the bug…

Why wouldn’t we prefer to test thoroughly the application and fix all critical failures before moving to production? Are architects, or Aeronautics engineers forced to deliver their work without ensuring quality? Then why are we, software companies?


This traditional point of view of Engineering processes (it has actually been long time used for Electronics design) might seem outdated when applied to web applications, and more precisely web “2.0” systems. Nowadays, projects need to develop fast, deploy quickly and have a soon ROI. Is it a misunderstanding to still apply these four principles?

It is not, in my opinion. While it might seem meaningless for that 80% of medium-small web sites based on a few interfaces and some custom CMS’s, it is absolutely necessary for bigger home-brew apps. Otherwise, spaghetti-code, lack of documentation, coupled modules and many other big mistakes shall occur and the time is to come were our beloved application will need to be rewritten from scratch, or fall into oblivion.

I am afraid I have seen it before, and not just once.