Tools and boxes and code design

A good metaphor of application design is to think about each piece of your software like a physical tool. You may have just one tool for the current job, or a set of very few tools, in which case it makes sense to keep them all in the same box. But as you add more tools, it becomes more and more difficult and inefficient to find them in one big box, so you should start putting them in separate boxes.

Of course you should not assign tools randomly to the boxes: you must define a set of guidelines so that you know where to put and to retrieve any given tool. This means:

• when you start building new boxes, you plan carefully what each box is meant for
• when you have to decide where to put a tool, you think carefully about is the most appropriate box
• you may also change idea later and move it to a different box, as long as this is also the result of careful thought
• you stick professionally to such guidelines each time you add a new box or a new tool

For people who never really paid much attention to application design, moving to a structured application is a difficult mindset change. They are used to put everything in one place, and suddenly it seems they have to look into many different files / classes / methods to follow the whole process. But if the application is well designed and the underlying design is understood, it becomes much quicker and easier to find and debug a specific piece of code.

Now, if we agree that a structured application is a good thing, we should also agree that it’s the job of a good developer to make the design as self-evident as possible. Each developer is usually able to decode his/her own design, but other developers may not understand it quickly unless you make it really really clear and umistakable. How do you achieve this?

* Good naming will always be the most effective skill. If namespaces, classes and methods are really well-named, it will be easy to follow the design.
* Refactoring is a must. Good design usually cannot be achieved immediately, so cleaning up, moving and renaming things is mandatory to get it eventually.
* Documentation. Some pieces of your code may be complex and non-intuitive despite good naming and refactoring. In that case, add a README or a comment to explain what they do.

In conclusion: always take care of your boxes, your tools and your code, and everyone (including you) will be grateful for it.