Thoughts on file organisation

[David Mearsen]

Hi,

I've recently started programming C after many years using "the other
language"... I just wanted to find out the common practice for
organising source files.

Specifically, consider a moderately complicated library module, mylib.c.
Obviously its "public interface" (i.e. non-static function
declarations, typedefs, any global variables) need to go in mylib.h.

The question is: what about private (i.e. static) functions and struct
declarations and typedefs only used in the private implementation?

Is it more usual to put these in the mylib.h file, or to put them at the
top of the mylib.c file, or to create a separate mylib_private.h file?

And a similar question for #includes: let's suppose that one of the
public functions declared in mylib.h takes a FILE* parameter.
Obviously, I'll need to #include<stdio. hat the top of mylib.h to get
the FILE structure defined.

But say in the implementation, in mylib.c, I need to use (for example)
malloc. Then I need to #include<stdlib .has well. Should I put the
#include at the top of mylib.h or at the top of mylib.c?

Thanks for any input!

DM

[Willem]

David wrote:
) I've recently started programming C after many years using "the other
) language"... I just wanted to find out the common practice for
) organising source files.

What's "the other language" ? Cobol ?

) Specifically, consider a moderately complicated library module, mylib.c.
) Obviously its "public interface" (i.e. non-static function
) declarations, typedefs, any global variables) need to go in mylib.h.
)
) The question is: what about private (i.e. static) functions and struct
) declarations and typedefs only used in the private implementation?
)
) Is it more usual to put these in the mylib.h file, or to put them at the
) top of the mylib.c file, or to create a separate mylib_private.h file?

My personal prefecernce is to put them at the top of the .c file.
*_private.h files are useful when you have several .c functions that
form a package/module/library.

Also, if you define static functions before you use them, you don't need
to define them, which removes redundant information. IMO, this is a good
thing, but other opinions may differ.

) And a similar question for #includes: let's suppose that one of the
) public functions declared in mylib.h takes a FILE* parameter.
) Obviously, I'll need to #include<stdio. hat the top of mylib.h to get
) the FILE structure defined.
)
) But say in the implementation, in mylib.c, I need to use (for example)
) malloc. Then I need to #include<stdlib .has well. Should I put the
) #include at the top of mylib.h or at the top of mylib.c?

I'd say, at the top of mylib.c.
There are also people who don't include any system libs in a .h file,
but specify that it needs to be included whenever mylib.h is included.
I personally think it's a bad practice but I've seen it done.

Bottom line: keep the .h file to a minimum, but make sure it can stand
alone. This is my personal opinion, of course. It might, or might not
be the "industry standard".
SaSW, Willem
--
Disclaimer: I am in no way responsible for any of the statements
made in the above text. For all I know I might be
drugged or something..
No I'm not paranoid. You all think I'm paranoid, don't you !
#EOT

[santosh]

David Mearsen wrote:

Hi,

I've recently started programming C after many years using "the other
language"... I just wanted to find out the common practice for
organising source files.

Specifically, consider a moderately complicated library module,
mylib.c. Obviously its "public interface" (i.e. non-static function
declarations, typedefs, any global variables) need to go in mylib.h.

The question is: what about private (i.e. static) functions and struct
declarations and typedefs only used in the private implementation?

Is it more usual to put these in the mylib.h file, or to put them at
the top of the mylib.c file, or to create a separate mylib_private.h
file?

IMHO, the last option is the best one.

And a similar question for #includes: let's suppose that one of the
public functions declared in mylib.h takes a FILE* parameter.
Obviously, I'll need to #include<stdio. hat the top of mylib.h to get
the FILE structure defined.

But say in the implementation, in mylib.c, I need to use (for example)
malloc. Then I need to #include<stdlib .has well. Should I put the
#include at the top of mylib.h or at the top of mylib.c?

The latter.

Thanks for any input!

DM

[Eric Sosman]

David Mearsen wrote:

Hi,

I've recently started programming C after many years using "the other
language"... I just wanted to find out the common practice for
organising source files.

Specifically, consider a moderately complicated library module, mylib.c.
Obviously its "public interface" (i.e. non-static function
declarations, typedefs, any global variables) need to go in mylib.h.

The question is: what about private (i.e. static) functions and struct
declarations and typedefs only used in the private implementation?

Is it more usual to put these in the mylib.h file, or to put them at the
top of the mylib.c file, or to create a separate mylib_private.h file?

"Private parts" don't belong in the public header file,
because they would then cease to be private and would become
part of your published interface. If you can, keep the private
definitions inside the library's .c files. If the library has
several .c files that must share a set of private declarations,
putting them in a mylib_private.h file is about the best you
can do.

A somewhat related matter: It is an excellent idea to
#include "mylib.h" in all the library's source files. That
way, the compiler can alert you if the declarations and the
definitions get out of step.

And a similar question for #includes: let's suppose that one of the
public functions declared in mylib.h takes a FILE* parameter.
Obviously, I'll need to #include<stdio. hat the top of mylib.h to get
the FILE structure defined.

But say in the implementation, in mylib.c, I need to use (for example)
malloc. Then I need to #include<stdlib .has well. Should I put the
#include at the top of mylib.h or at the top of mylib.c?

Opinions differ on this one. I am of the "headers should
#include other headers if they need them" persuasion, but there
is also a "nested #includes are evil" party to which some non-
stupid people belong. Choose your allegiance, and thereafter
do not waver.

--
Eric Sosman
es*****@ieee-dot-org.invalid

[fnegroni]

You will also find that in regular linkers, you will find yourself
declaring *one* public function per .c file.
Reason being linkers on unix, in general, are dumb, in a good way, and
try and keep binary compatibility amongst object formats by not
splitting functions themselves.
What this means is that if you have a large library, chances are your
client code will only use a bunch of the functions, and will most
likely appreciate if the static linking only takes place for those
functions that are actually used.
Dynamic linking doesn't impose such restriction, but it is good
practice, in library code development, to place each public function
in separate files anyway to reduce source control and maintenance
headaches.

[Malcolm McLean]

"David Mearsen" <no************ @nospam.comwrot e in message

>
I've recently started programming C after many years using "the other
language"... I just wanted to find out the common practice for
organising source files.

Specifically, consider a moderately complicated library module, mylib.c.
Obviously its "public interface" (i.e. non-static function
declarations, typedefs, any global variables) need to go in mylib.h.

The question is: what about private (i.e. static) functions and struct
declarations and typedefs only used in the private implementation?

Declare everything you want user to be able to access in "mylib.h". He ought
to be able to get the lot, except maybe FILE *s and the like, by simply
including one file.
Personally I expose most structures (though not in Baby X, my X windows
toolkit) to help debugging or coding round library mistakes, even if
intended to be opaque.

Unfortunately mylib might well depend on something, for instance the highly
general string functions I suggested in the xmalloc string functions post.
Ideally we would like these to be private to mylib.h to avoid creating
complex dependencies. There might also be functions which are uniqure to
mylib.h, but not suitable to call directly, and cannot sensibly be declared
static.

The multiple dependency problem is a very real one. A simple cross-product
routine can suck in "vector.h" and "vector.c" which sucks in a load of
matrix algebra, typedefs for floats, a fast sine library, and a special
memory allocator. There's no real answer in standard C. I'd say it is the
number one weakness of the language.

--
Free games and programming goodies.
http://www.personal.leeds.ac.uk/~bgy1mm

[Andrey Tarasevich]

David Mearsen wrote:

>
I've recently started programming C after many years using "the other
language"... I just wanted to find out the common practice for
organising source files.

Specifically, consider a moderately complicated library module, mylib.c.
Obviously its "public interface" (i.e. non-static function
declarations, typedefs, any global variables) need to go in mylib.h.

The question is: what about private (i.e. static) functions and struct
declarations and typedefs only used in the private implementation?

Is it more usual to put these in the mylib.h file, or to put them at the
top of the mylib.c file, or to create a separate mylib_private.h file?

If your idea of a "module" is synonymous with a ".c file", the you don't need an
extra file since you can indeed put all internal declarations at the beginning
of the .c file. I don't see the point of creating an extra include file for
this. The rationale for creating an include file is to be able to include it
into several translation units. This obviously doesn't apply here.

However, I personally find the it is more useful not to restrict a concept of a
"module" to a single implementation file. In that case a three-level file
structure might make sense. There's a single "external interface" include file,
like 'mylib_api.h', which declares the external interface of the module. There's
one or more "internal interface" files, like 'mylib1.h', 'mylib2.h' etc, which
declare interfaces between various implementation files within the module.

And a similar question for #includes: let's suppose that one of the
public functions declared in mylib.h takes a FILE* parameter.
Obviously, I'll need to #include<stdio. hat the top of mylib.h to get
the FILE structure defined.

But say in the implementation, in mylib.c, I need to use (for example)
malloc. Then I need to #include<stdlib .has well. Should I put the
#include at the top of mylib.h or at the top of mylib.c?

If you don't need any declarations from <stdlib.hin the .h file, then put it
in .c file. However, obviously, keeping it formally "clean" within this approach
might require a considerable maintenance effort. Let's say eventually you'll
need something declared in <stdlib.hin your .h file. Then you'll have to add
the declaration to your .h and remove it from all of your .c files. And vice
versa. At least with standard headers, it might prove to be more efficient to
always include them into .h files.

Also, sometimes certain compiler features (like pre-compiled header support)
might dictate their own style of header inclusion.

--
Best regards,
Andrey Tarasevich

[santosh]

cr88192 wrote:

>
"David Mearsen" <no************ @nospam.comwrot e in message
news:sl******** ***********@nos pam.invalid...

>Hi,

I've recently started programming C after many years using "the other
language"... I just wanted to find out the common practice for
organising source files.

there are many "other languages"...

a simple hueristic ranking would look something like this:
1. C++
2. Java
3. VB
4. C#
5. Python
6. Perl
...

I think it's fairly clear that he means C++, which is often jokingly
called "That Other Language" by some C programmers.

<snip>

[Keith Thompson]

"cr88192" <cr*****@hotmai l.comwrites:

"David Mearsen" <no************ @nospam.comwrot e in message
news:sl******** ***********@nos pam.invalid...

[...]

>Specifically , consider a moderately complicated library module, mylib.c.
Obviously its "public interface" (i.e. non-static function
declarations , typedefs, any global variables) need to go in mylib.h.

also, be careful with terms like "obviously" as well.
if one is wrong, then it can make them look arrogant and/or stupid...

now, not all non-static functions are part of the "public interface"
either (this is especially true once the complexity of a library moves
much past "trivial").

If a function isn't part of the public interface, why would you not
declare it as static?

[...]

--
Keith Thompson (The_Other_Keit h) <ks***@mib.or g>
Nokia
"We must do something. This is something. Therefore, we must do this."
-- Antony Jay and Jonathan Lynn, "Yes Minister"

[Ian Collins]

Keith Thompson wrote:

"cr88192" <cr*****@hotmai l.comwrites:

>"David Mearsen" <no************ @nospam.comwrot e in message
news:sl******* ************@no spam.invalid...

[...]

>>Specificall y, consider a moderately complicated library module, mylib.c.
Obviously its "public interface" (i.e. non-static function
declaration s, typedefs, any global variables) need to go in mylib.h.

also, be careful with terms like "obviously" as well.
if one is wrong, then it can make them look arrogant and/or stupid...

now, not all non-static functions are part of the "public interface"
either (this is especially true once the complexity of a library moves
much past "trivial").

If a function isn't part of the public interface, why would you not
declare it as static?

It might be called from a different compilation unit within the library.

--
Ian Collins.