Tips for writing complex code

I admit, when I know I have to a complex code I get as excited as finding my parents' secret chocolate box after they went to sleep. It's really hard to say - 'all right, let's slow down and make it right with conscious decisions'. Nah, it has to be like a diarrhea. So let me share what I do in that excited state to make the code proper.

First of all, there are professional books that can tell this much better. It's not magic and there were many before investigating this topic. But some good tips are always great, I hope so.

What I mean by complex code? It can be a Drupal module, an API, plugin - anything that has a business logic in it - but not too hard that it would require days to develop.

Probably the most important when you are about to start is not to start - but to think. (How genuine idea, huh?!) Yup, many times it's forgotten that developers have to think. Or it's just awkward sitting in the office and not touching the keyboard. Thinking builds up the whole system in your head - and gives you the freedom to focus. Coding ties down lots of attention - so eventually you start cutting corners and be illogical. You don't want to hit Ms Information on her face, right?

Then take a paper and draw. I'm using Adobe Ideas a lot. It allows you to use layers and zoom really easily. Zooming actually super useful to create separate sections, work out them and then see the whole picture, connect items. You can store them in the cloud and use over many devices.
But also a simple clean sheet will do a similar job. I believe physical tools are much better in that case.

In general I'm a veryvisual type (veryvisual is a subclass of visual person type) - who has to see almost everything in order to understand. That I follow in code as well.

Then you eventually start coding. As a guideline I try to spread the code on light layers, one level at a time - if possible. It doesn't even have to work or be complete. The important part is that you can see what are the domains, what sections will communicate to each other and what contains the different parts of the data structure.

To make it work as soon as possible I create fake variables and returns - in order to make a function work. You only have to care about the format:

function my_load_object() {
  // Real logic comes this summer.

  return array(
    'name' => 'hardcoded-name',
    'price' => '1234.12',
  );
}

Next thing I do always is build up steps - almos like a template pattern - in comments. You think through what steps you will make and leave separated comments in the function:

function sortof_complex_method() {
  // loading items from db

  // sanitize items

  // - fix currency

  // - add banners

  // populate latest history arrays

  // ...

}

When you have the steps first then it's much easier to fill out the details and keep yourself on track.

Then as a last trick I use @todo extensively. I usually use 2 kinds of todos. One to mark the steps I really have to do and the code wouldn't be complete without that - but I have just too many things in mind and want to concentrate on other things:

function clear(){
  // @TODO add cache clear mechanism
}

And the other one is just a reminder that some parts would need refactoring, improvement or good-to-have-s. It can be anything that is not essentially required by the business logic but would improve on the code otherwise:

function clear(){
  // important cache code
  ...
  // @todo add log message and save size of cache for statistical purposes
}

You can use the lower case to make them separate if you want.

---

These are the most used techniques of mine and I'm really curious how you deal with writing complex code.

Peter