Code != Clothing, or How to neatly structure your code

Having been worked with countless technologies , frameworks  and 3rd party libraries, I can say that I have seen almost every possible way of organising the code for a project. From the approach of putting every file in a single folder “just for now” (where “now” becomes “forever”, because moving things around is just too complicated), to the one of creating humongous, monolithic do-everything libraries (which I nicknamed “walls of code”), to have everything is in one place, to the theoretically more rational modular system, where files are organized in sub-folders.

The reason why I stress the word “theoretically” is that, while the idea is certainly good, it can still lead to a messy, hard to maintain mass of files. The key of everything, in this case, is finding what logic should be used to structure the code. It may seem a simple question to answer, but the way one answers to it can lead to nasty surprises.A common, yet, in my opinion, very inefficient way of organizing the code is what I call The Sock Drawer. I gave it such name because it reminds me of how most people manage their clothing. Let’s have a look at it in detail and see why I think it’s not appropriate for code.

The Sock Drawer

The Sock DrawerSince childhood, we are taught that keeping our room tidy is a good thing. The motto is “a place for everything, and everything is in its place”. If we apply this logic to out clothing, it seems obvious that the best thing to do would be grouping them together. Socks in a drawer, underpants in another, shirts in another. Trousers in yet another drawer, separating the good ones from the old, consumed ones we use when gardening, and, finally, shirts, jackets, suits and elegant clothing in the wardrobe (again, grouped by purpose).

Once finished, we can see how everything is tidy and organised. And it works perfectly, too! Time to dress up: open drawer, here’s a t-shirt. Open another, here are the underpants. One more drawer, here are the socks. Trousers, shirt, jacket, everything in its place. We only have to match the type (elegant/casual) and the colours, and we’re done! It’s such a natural thing, it only makes sense to apply it to our code… Or is it?

The Code in the Sock Drawer

By following the same principle we apply to our clothing, we come to the conclusion that code of the same type goes in the same place. Let’s take, for example, Magento, a popular e-commerce derived from Zend framework which follows the MVC principle and organises the code using the Sock Drawer technique. Here’s the typical structure of a plugin providing some functionality and requiring both a frontend and a backend interface:

  • /app
    • /code – All Model and Controller code goes in a sub-folder of /code
      • /local
        • /MyNamespace
          • /PluginName (this
            • /Block – Some Controller code goes here
            • /controllers – Some other Controller code goes here
            • /etc – Plugin’s configuration XML files go here
            • /Helper – Helper code goes here
            • /Model – Models code goes here
            • /sql – SQL code goes here
      • /core
        • [folder tree analogous to the one found in /local]
      • /community
        • [folder tree analogous to the one found in /local]
    • /design – Part of the View code goes here (PHP code)
      • /adminhtml
        • [several other nested folders]
      • /frontend
        • [several other nested folders]
    • /etc
      • /modules – Configuration files that enable plugins go here
  • /skin – Part of the View code goes here (CSS and JavaScript)
    • [several sub folders, each one containing CSS, images or JavaScript files]

Apart from the difficulties in following such structure, two problems arise from this layout:

  1. Development becomes significantly more complicated. While installation on a production site might be a simple matter of copy/pasting folders (if the structure is correct), Developers don’t copy and paste files every time they change, they use symlinks. This means creating a dozen or so symlinks (if not more), and recreate them if a file gets renamed. It’s definitely a mess. Put a link in the wrong place, and thing will suddenly break, apparently without reason.
  2. Uninstalling a plugin becomes a nightmare. Remove a folder here, another there, a file here, a file there… No, not that file. Wait, the other one.
OpenCart, another popular e-commerce, is also “guilty” of using such practice, with the difference that your plugin’s code is divided in files, each one going in a different folder inside the framework’s folder tree.

While initially it looked like a good idea, sorting the code by type revealed itself not to be such a great choice. So, how comes this works with socks? That’s because clothing is interchangeable, while code is not necessarily so. A pair of socks goes well with several trousers, which go well with several shirts, which go well with several jackets. You reuse small components and make an outfit out of them. On the other hand, the code for a plugin, library or framework is designed to go together and should stay together.

A better approach: the Uniform

Fortunately, there’s a simpler way to organise your code. Keeping the comparison with clothing, think of your plugins, modules or libraries as uniforms. You need shirt, jacket, trousers, socks, tie and shoes, and they must go together. You store them together, you use them together, you throw them away together. They all stay in the same storage bag.

This is the approach used by Vanilla Forums: a plugin goes into its own folder, inside which you’re free to structure the code as you wish. Here’s how the folder structure looks like:

  • /plugins
    • /MyPlugin
      • /SomeFolder – Name it as you like
      • /SomeOtherFolder – Name it as you like
      • class.myplugin.php

Sure, inside the MyPlugin folder one will still have “drawers”, but they will only contain resources needed by your plugin. All the pieces are well organised, but in one place. Let’s see how this compares to previous method:

  1. Development is easy. Just create one single symlink to your plugin folder, and you’ll magically have it installed.
  2. Deployment is also easy, just one folder to copy.
  3. Removal is trivial: delete one folder, plugin is gone. No files left around, no accidental deletions.

It seems clear to me which of the two methods is the most effective.

Bottom line

Clearly, I favour the second method over the first. Code is not clothing, and what works together must stay together. If two or more components need to share resources, move those into a separate component. Make your libraries live next to each other like good neighbours, but don’t let them become house mates, and you won’t have fighting for the TV.

Photo by Jeremy Beagle
0 replies

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published. Required fields are marked *