FipS`Code Documentation

Introduction

FipS' Code is a set of C++ code pieces which I consider general and insulated enough to be useful for other developers. The code is organized in a directory structure which corresponds to the structure of namespaces. I try to minimize dependencies between unrelated parts. So it is often possible to use only a few related source files thus your project can stay simple & clean.

Compilation

The code is distributed in a form of source files, so it is quite easy to integrate it into a project. Just add it to the source tree! The only thing required is to add the root directory 'fs' to the additional include directories in the compiler / project settings as it is internally used (the headers are referenced like this: #include<fs/...>). For instance for Visual C++ 7.1 it could be found here: Project / Properties / C++ / General / Additional Include Directories.

Configuration

Some of the code can be externally configured through certain preprocessor directives. In that case it is possible to define preprocessor directive FS_INCLUDE_USERDEFS (preferably in the compiler / project settings), then the user defined header file 'fsUserDefs.h', located in the root directory 'fs' is injected into each header. It is the right place for overwriting default configurations without source code modification.

The default module setting is typically overwritten by defining FS_<...>_USERDEFS as is seen in the example below (fsUserDefs.h):

    #define FS_ASSERT_USERDEFS // overwrite default settings
    #define FS_ASSERT_LABEL "MY ASSERT WARNING"
    #if !defined(NDEBUG)
    #    define FS_ASSERT_ENABLE_BOX
    #    define FS_ASSERT_ENABLE_BEEP
    #endif

Design Notes

The code constructs used are limited to be compilable with an older Visual C++ 6.0-like compiler, which I am using for my Pocket PC project. So I had to sacrificed some features like local classes or more advanced template stuff. It would be nice to relay on a modern ANSI / ISO compliant compiler and involve Boost etc. but I hold the view that it is still not the best way for a generic code base at preset. Nevertheless Boost-like way is a must for concrete projects when the target platform & compiler are defined well.

Certain C++ patterns are involved to provide as simple client interfaces as possible. The PIMPL idiom is used to hide the complexity of private interfaces and sometime helps put STL dependencies out of headers. The RAII helps manage the lifetime of resources and makes them easier to handle.

Error Checking

There are no exceptions involved. Error checking is done through return codes. Moreover almost all more complex classes have 'IsValid' member function which can be used for checking the internal state of an object (it also indicates whether or not the constructor failed).

Functions in public interfaces check their input parameters for correctness. If an incorrect parameter is passed to the function, it returns immediately. FS_VERIFY_RETURN and FS_VERIFY_RETURN_VAL are employed to keep the error checking code simple.

A typical high-level implementation can be seen below:

    bool Foo::SetName(const char *pszName)
    {
        FS_VERIFY_RETURN_VAL(IsValid(), false); // invalid internal state
        FS_VERIFY_RETURN_VAL(pszName, false); // invalid input parameter
        
        //...
    }
FipS' Code (Thu Feb 15 22:43:35 2007) - (c) Filip STOKLAS (FipS) - [ www ] [ Guest Book ]