Structuring libraries, basic design tips.

Posted by on August 28, 2009

One of the most important things a programmer has to know and learn is proper code design, structuring of the code, etc. This may not be imperative for you if you’re just starting out, but sooner or later you’ll be able to spot the patterns and realize that your current way of doing things is not optimal but rather cumbersome. This is when you start to separate things into modules and you begin to design your code with more meaning and purpose.

By breaking your code into modules or “classes” you can have a finer granularity of the code itself, you can encapsulate the base code and work on top of it, you can also reuse the code in other projects if you have a good design. An example would be a log library (for logging useful debugging information onto text files) with proper design and care you’ll be able to use the same library in almost all of your projects with little to no modification at all.

The main points you should never forget about are:

  • Instancing
    • This is when you create an “object” – And as you create it, you should also be able to destroy it. (Constructors / Destructors in OOP). An object factory may be implemented (this would be another class) to handle the instances. In CPP you may use smart pointers, but we’re talking about PB in this case.
  • Members
    • In our case a main structure is used as the “members” (Again, in reference to OOP) – This structure is instantiated by the constructor or “create” function. Don’t forget that anything you allocate you should also be able to deallocate. It doesn’t matter if the language or OS handles it underneath; it’s bad coding practice to avoid such trivial – but important – code.
  • Methods
    • They give you functionality, in PB there are no methods but a similar concept applies: you have functions or routines that you create specifically for the library itself. Some may be of the Get / Set type (which either get or set a variable) Or other methods such as converters, helpers, accesibility calls, etc.

All together they make a class; in our case a library.

Let’s write one and follow by example!

Imagine you needed to encapsulate the random functions to provide extra functionality, then all you need to do is first define a structure (if you’re going to have members; for instance do you want the library to “remember” the previous and current numbers?, if so you would need a structure!)

Alright, now we need to write our constructor and destructor functions! This will create and destroy the instances.

That’s not too bad, first we allocate an instance and then we populate the member variables just to return the pointer of our new “object”. The destructor simply frees any allocated memory and clears out the pointer itself.

Now we need to define our library functions, in this case we only need one so we may generate a random number and keep track of the previous and current numbers.

That’s ok, but we can still add functionality. For instance, we need a way to access the structure fields (or “members”) without having to cast pointers, etc. We can do this by implementing a few Get/Set routines. In this case we only need to get the previous and current numbers, so…

But wait, we can still add functionality! such as utility functions, in this case we would like to fill a given array with random numbers, so…

And while we’re at it, let’s fill lists as well!

If you don’t need to keep track of the current and previous numbers, you can just opt out the instancing system and modify the utility calls to work in an “instance-less” mode, however that’s up to you.

But, let’s take it for a ride first!

Ok, so we tested the instancing and most if not all of the “methods” we just created. By now you should realize how useful such systems can be if you happen to design them correctly.

This particular lib could be extended to support averaging of the numbers, median / mean, etc. You could even implement a custom PRNG and give the option to choose between yours and the built-in one!.

You may download the entire source from here. As an exercise you could implement the Get/Set methods for the Seed.


PS: Someone remind me to update the language file for GeShi and to fix the font :) (The indentation is all wrong!)