I was going through the outstanding book “Code craft The practice of writing excellent code” by Pete Goodliffe. It has a lot of tips I wish I had when I started programming. Part of the book is about code guidelines which got me thinking.

Is ignoring code guidelines really what makes software hard to read or understand?

Definitions of complexity have been setup and thoroughly discussed. More on this here: https://en.wikipedia.org/wiki/Cyclomatic_complexity

I would like to propose another metric. To illustrate my point I need to introduce a new (as far as I know) kind of diagram.

Process diagrams

First let’s define what a process is. A process is anything that changes the state of an entity/object. An example would be motion blurring an image.

process diagram for gaussian blur

The big arrow indicates a process: “Gaussian blur of an image” which will change some state: “the Bitmap pixel values”. State is displayed as Venn diagrams.

The gaussian blur parameters have an obvious impact on the blur process but are not changed by the blurring process.

Now we have a simple way of discussing processes and state.

An example where code guidelines never helped

Now let’s consider a webapplication in which we use a message queue to process videos. Here is a process diagram on how that works:

A simple video processing process

The process is simple.

  • A user uploads a video and adds some parameters on how to process the video.
  • The web application puts the uploaded file in a directory and puts a message on a message queue.
  • Later on another process picks up the message. This message is then removed from the message queue and the video is processed.
  • The finalized video gets dropped in a “processed video files” directory and the uploaded video is deleted.

This is simple enough. But let’s say Jimmy is looking for a raise. He wants to prove himself and how better to do this than to wow everyone with something complex? (Based on a real story)

The idea is that we want to give priority to paying customers. Also we want the user to be able to cancel video processing.

Jimmy, victim of my story on bad design, will be adjusting the messages in the queue directly. A process ‘priority requeuing’ bumps free users back to start of the queue every time a paying customer comes along.

While we’re adjusting the queue anyway, Jimmy will also go over the queue and remove messages if they are cancelled. This way the queue is only filled with actual work! Very clever!

If you’ve ever heard about race conditions you know trouble is ahead.

A better and simpler design, however, would be to have multiple queues. One for free users, one for paying customers. Please don’t adjust the queue directly. It’s a queue for a reason.

Many other designs are possible. But some are simpler or better than others.

Conclusion

Now, what was the point of all of that?

If you are doing a code review. Are you really looking at the process? Or are you just looking at brackets and class names? I know I have been. Maybe it’s time to start visualizing the processes and have long debates about that instead?

My advice? Keep your processes clean and simple and you’ll spend less time babysitting chaos.