Taking more of my own advice...

I’m continuing to work through my list of things to do for The Server Framework (and all the libraries that support it) and I’ve recently got to the ‘set up Doxygen and do a bit of documentation’ item…

I’m a firm believer that code should be documented once it has stabilised; I don’t tend to write many code comments as I prefer to try and make the code as self documenting as I can but for a tool like Doxygen to be worth using for more than just the pretty pictures it’s best to add some comments to explain what things are and how they hang together. Thus I have no excuse for not documenting some of this code now as it has been around for long enough to be considered ‘stable’ (some of it dates from 1997…) and the Doxygen and chm files are useful for the ever increasing users of The Server Framework.

I’ve always found that writing about code tends to lead to better code; when you have to explain in detail why things are how they are you can’t hide bad design in hand waving. This documentation exercise is no different. As Doxygen draws diagrams that I don’t like I am forced to think about why the code is like it is and whether it should be different; sometimes it should be…

Right now I’ve decided to take another piece of my own advice and I was nudged in this direction by a documentation difficulty… The issue is with the use of explicit callback interfaces or virtual methods; something that I pondered a while ago here. Quite a lot of code that I’ve written seems to prefer the virtual methods method, I’ve changed my mind on this, I think it’s generally better to provide callback functionality with an explicit callback interface. Thus code like this:

CThread
{
   ...

   virtual int Run() nothrow() = 0;

   ...
};

Becomes:

IRunnable
{
   public : 
      virtual int Run() nothrow() = 0;
};

CThread
{
   public :
      explicit CThread(
         IRunnable &runnable);
   ...
};

This makes the interface that the CThread object uses to communicate with your code clearer and makes both CThread and the requirements on your code easier to document.

When I was thinking about reasons for doing this either way I came to the conclusion that since, by taking the explicit interface route, you could build exactly the same code as by not taking the explicit interface route (i.e. you could inherit from both CThread and IRunnable) yet by taking the inheritance route you couldn’t (i.e. you must inherit from CThread) the more flexible (and generally just cleaner feeling) route was best…

So, as usual, I wait for code to stabilise before documenting and the act of documentation destabilises the code…