Question

How do you usually go about when you need to design a module? Till now I’ve taken care of how easy it is to use, how intuitive its API is, extendibility, performance and stuff like that.

But what seems fairly simple and straight-forward to me might seem over-complicated for other users. Although it doesn’t happen that often, it does happen sometimes to all of us (I hope).

Are there any questions that you should ask yourself before designing a class hierarchy/API/whatever before you proceed with coding, other than the issues I already mentioned?

If you believe the question is better suited for a different section on SO please feel free to migrate it, but I’d still like an answer.

Cheers.

Answer 1

Your question is a very good one, and one that has answers, but so complicated that the answer is basically the experience in programming.

There are general principles to make software, but I think that here, in this short answer, I can give you one concept that you can apply. Software is a representation of a domain (such as a bank software is made to tailor the financial system, or a radar software is made to tailor the ideas and principles of radar detection). Software, therefore, is like a theory: it fits the current knowledge of your domain perfectly, allows inferences and extensions. If more knowledge becomes available, the theory should be extended, polished or made more general to accommodate this new knowledge, while still remaining valid for the previous knowledge.

Hence, all the concepts about theories apply:

• satisfy the requirements imposed by your knowledge in a unified framework that sounds homogeneous and well integrated.
• be simple, but look for patterns that you may make more general, and spotlight these patterns for better integration.
• don’t be too simple. If your software does not fit the requirements, your theory is too limited and must be extended.
• allow your software to accommodate new requirements, software is not cast in stone. it mutates and evolves, accommodating the new requirements, or losing functionalities that are no longer needed.

So, software should be minimalistic but not too much, beautiful but practical.

When it comes to put into practice these directions, I suggest you to allow time for learning your domain. You can’t model something that you don’t understand. Learn the basics, and start from something simple, then progressively refine them. You will occasionally see that some things “feel” in the wrong place. Ask yourself questions such as

• “who is responsible to do this operation?”
• “Is this dependency logical and needed for this object to work, or is it just a spurious one due to bad code organization?”
• “Is this high-level or low-level functionality?”
• “Am I repeating this ?”
• “can I change this object/layer/subsystem internally without the code outside knowing ?”
• “can I extend this in the future without ruining or invalidating the past ?”
• “can I test and probe this functionality easily for correct behavior ?”
• “Is it easy and intuitive to understand and use ?”
• “can I recombine what I already have easily and without touching to implement new behavior?”
• “Is this functionality isolated so that I can show it to the outside world without the bulk of the rest of the code I manipulate ?”