Thread: Most readable way to organize variables and files?

In principle, you have

lib.h
This contains all the public interfaces to your library, consisting mostly of function prototypes, structures and #defines. Ideally, no variables should be in here.

Later on, if things get really large, you may choose to split this up, so that lib.h includes say lib-api.h and lib-tools.h

lib.h is the only file which users of your library ever see - apart from the library itself. Though they may find a read-only copy of the source code useful with a debug version of the library.

private.h
This contains all the public information which needs to be shared internally to your library, but which is hidden from the users of your library.

This too can be broken down into many files later on.

C++ has namespaces for hiding names from the user. In C, a common technique is to prefix all global symbols with a short (2 to 4) string. Eg OpenGL uses "gl" as it's common prefix.

Not only does this help to identify your library, it also helps when you want to implement a routine with a common name like read()

Within each source file, make as many things as you can 'static'. This localises the scope of the symbol to be just in that source file. This helps no end in figuring out what the dependencies are.

Even though you're writing in C, it helps to organise things on a C++ line - like grouping common functions into the same source file, and using a header file to describe the interface to that source file (like you would with a C++ class.h and it's implementation class.cpp)

Well

Code:

/************mylib.h************/
#ifndef MYLIB_H
#define MYLIB_H
#include <mystring.h>
#include <myio.h>
#endif /* MYLIB_H */

Code:

/**********myio.h****************/
#ifndef MYIO_H
#define MYIO_H
/* All myio public stuff */
#endif /* MYIO_H */
/********************************/

If you want to make sure that they only include mylib.h and don't sneak around and directly include myio.h, then do something like this

Code:

/************mylib.h************/
#ifndef MYLIB_H
#define MYLIB_H
#include <mystring.h>

/* check myio was not included already from somewhere else */
#ifdef MYIO_H
#error Don't include myio.h yourself, only include mylib.h
#endif
#include <myio.h>
#endif /* MYLIB_H */

/**********myio.h****************/
#ifndef MYIO_H
#define MYIO_H

/* were we included from mylib? */
#ifndef MYLIB_H
#error myio.h included without mylib.h
#endif

/* All myio public stuff */
#endif
/********************************/

OK, they may figure out that
#define MYLIB_H
#include <myio.h>
works, but then you have a real excuse to use this


> just putting them in those seperate headers would be enough?
That would be enough

> could I declare them in say pmystring.h and include that from mystring.h?
Putting them in pmystring.h is good
#include "pmystring.h" in mystring.h is bad
It kinda offers temptation to the more curious library user to go looking inside pmystring.h to see what goodies there are.

Your source code should be like this

Code:

/* mystring.c */
#include <mylib.h>  // gotta obey your own rules
#include "pmystring.h"  // our private stuff
...

Here's a bit more on nested include files
http://www.eskimo.com/~scs/cclass/int/sx6b.html

I think it's OK to use nested includes in your lib.h, since this makes it simple for your users to
#include <mylib.h>
and not worry about what else they need to include.

But I would stay away from

Code:

/* mystring.c */
#include "everything.h"
...

as a means of saving yourself a bit of typing. In a large project, such techniques create far too many pseudo-dependencies, which cause tools like "make" to recompile a whole bunch of stuff which didn't need recompling.
It also makes it difficult for you to figure out "what does this module depend on" if you're planning any porting or re-use of code.

OK, they may figure out that
#define MYLIB_H
#include <myio.h>
works, but then you have a real excuse to use this

Lol yea.

Thanks a ton I completely understand everything now and know exactly how to do it. That is a pretty sneaky way of using defines and I don't think I would have ever figured it out on my own. It is an awesome explanation and I think it should be added to the FAQ, or an entry like that should be added. I noticed it was on the to-do list heh. I did alot of searching and just ended up finding info on using ifndef to making header files idempotent and alot of other useful stylistic things like this. Nothing explained how to use multiple header files in that way, they usually only showed one example. Again thanks this has been a great help.

Oh also I took your advice and made all my variables for my IO functions static to the same C file. After going throught it all I realized I was using every variable in at least 3 different functions so I made them all static. It made it
way easier to read. Thanks again.