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.h> at 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.h> as well. Should I put the
#include at the top of mylib.h or at the top of mylib.c?

Thanks for any input!

DM

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.h> at 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.h> as 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

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.h> at 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.h> as 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

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.h> at 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.h> as 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
esosman@ieee-dot-org.invalid

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.

"David Mearsen" <no.spam.please@nospam.com> wrote 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 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

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.h> at 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.h> as 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.h> in 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.h> in 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

David Mearsen <no.spam.please@nospam.com> wrote:

> 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?

In mylib.c, except that you if you have shared declarations among
mylib_1.c, mylib_2.c etc. those need to go in a mylib_private.h .


> 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.h> at the top of mylib.h to get
> the FILE structure defined.

That's my preference. If I #include "mylib.h" I like my code to still
compile. Some programmers prefer to make you include stdio.h yourself,
and document that fact.

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

In mylib.c, because it is not needed to compile client code.


--
pa at panix dot com