Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.c > #103751 > unrolled thread

Private and public code

Back to article view | Back to comp.lang.c

Contents

  Private and public code GOTHIER Nathan <nathan.gothier@gmail.com> - 2017-02-12 20:03 +0100
    Re: Private and public code Ian Collins <ian-news@hotmail.com> - 2017-02-13 08:10 +1300
      Re: Private and public code GOTHIER Nathan <nathan.gothier@gmail.com> - 2017-02-12 21:38 +0100
        Re: Private and public code Richard Heathfield <rjh@cpax.org.uk> - 2017-02-12 20:58 +0000
          Re: Private and public code GOTHIER Nathan <nathan.gothier@gmail.com> - 2017-02-12 23:06 +0100
            Re: Private and public code Richard Heathfield <rjh@cpax.org.uk> - 2017-02-13 06:00 +0000
              Re: Private and public code GOTHIER Nathan <nathan.gothier@gmail.com> - 2017-02-13 08:31 +0100
        Re: Private and public code Ian Collins <ian-news@hotmail.com> - 2017-02-13 19:07 +1300
          Re: Private and public code GOTHIER Nathan <nathan.gothier@gmail.com> - 2017-02-13 09:14 +0100

#103751 — Private and public code

Hello everybody,

After reading many headers in different C projects, I realized the fact that there are many private code (macros, typedefs, ...) included in headers that makes difficult to distinguish what is useful for the end user.

Since I consider headers as some kind of minimal documentation for C programmers, I put every private code in source files and only public code in headers. Although it could lead sometimes to put all unrelated private code in one common source file with an include guard.

What do you think about this practice?

[toc] | [next] | [standalone]

#103752

On 02/13/17 08:03 AM, GOTHIER Nathan wrote:

Please limit your line length!

> Hello everybody,
>
> After reading many headers in different C projects, I realized the
> fact that there are many private code (macros, typedefs, ...)
> included in headers that makes difficult to distinguish what is
> useful for the end user.
>
> Since I consider headers as some kind of minimal documentation for C
> programmers, I put every private code in source files and only public
> code in headers. Although it could lead sometimes to put all
> unrelated private code in one common source file with an include
> guard.
>
> What do you think about this practice?

Why don't you just use a private header?

-- 
Ian

[toc] | [prev] | [next] | [standalone]

#103759

On Mon, 13 Feb 2017 08:10:36 +1300
Ian Collins <ian-news@hotmail.com> wrote:

> On 02/13/17 08:03 AM, GOTHIER Nathan wrote:
> 
> Please limit your line length!
> 
> > Hello everybody,
> >
> > After reading many headers in different C projects, I realized the
> > fact that there are many private code (macros, typedefs, ...)
> > included in headers that makes difficult to distinguish what is
> > useful for the end user.
> >
> > Since I consider headers as some kind of minimal documentation for C
> > programmers, I put every private code in source files and only public
> > code in headers. Although it could lead sometimes to put all
> > unrelated private code in one common source file with an include
> > guard.
> >
> > What do you think about this practice?
> 
> Why don't you just use a private header?
> 
> -- 
> Ian

Do you compile private headers? For me appending "private" to "header" looks weird... since we usually make public access to private code with headers. ;-)

[toc] | [prev] | [next] | [standalone]

#103761

On 12/02/17 20:38, GOTHIER Nathan wrote:
> On Mon, 13 Feb 2017 08:10:36 +1300 Ian Collins <ian-news@hotmail.com>
> wrote:
>
>> On 02/13/17 08:03 AM, GOTHIER Nathan wrote:
>>
>> Please limit your line length!
>>
>>> Hello everybody,
>>>
>>> After reading many headers in different C projects, I realized
>>> the fact that there are many private code (macros, typedefs,
>>> ...) included in headers that makes difficult to distinguish what
>>> is useful for the end user.
>>>
>>> Since I consider headers as some kind of minimal documentation
>>> for C programmers, I put every private code in source files and
>>> only public code in headers. Although it could lead sometimes to
>>> put all unrelated private code in one common source file with an
>>> include guard.
>>>
>>> What do you think about this practice?
>>
>> Why don't you just use a private header?
>>
>> -- Ian
>
> Do you compile private headers? For me appending "private" to
> "header" looks weird... since we usually make public access to
> private code with headers. ;-)

I use a private header whenever I wish to share information between two 
(or more) source files in a library but don't wish to share that same 
information with the user of the library. I don't particularly consider 
"private header" to look weird. Perhaps it's because you have accustomed 
yourself to thinking of headers as the "public interface" of a source 
file? That's understandable, but there are various degrees of "public".

Proof by analogy is fraud, but /illustration/ by analogy is valid. So 
here's an analogy for you. Think of a header as being a little like an 
HTML document. We normally think of HTML documents as being part of the 
World Wide Web, and so they seem to us to be "public" information. But 
many companies nowadays have internal Web sites on their intranets, and 
they use those sites to share information amongst their various 
departments, but they don't share them with the wider world.

Similarly, headers can be shared amongst source files in a module, 
without necessarily being published as part of the binary distribution.

This is particularly useful when "opaque types" are being used. An 
opaque type can be created by publishing a struct type declaration in a 
header without publishing the struct itself, often (but not necessarily) 
using a typedef, such as: typedef struct Bignum_ Bignum;

This isn't enough information for a source to define a Bignum object, 
but it /is/ enough information to allow the source to define a pointer 
to such an object. It can then receive such a pointer from a call to a 
function that creates these objects, and it can pass it to functions 
that can receive such pointers, without ever being aware of what it's 
actually pointing to.

Of course, the type must be defined /somewhere/. And if the module that 
manages the type can all be implemented in one source file, that's fine, 
but maybe for reasons of code organisation it is considered better to 
split that source into several files. In this case, they will all need 
to see the type definition, without revealing it to "user" code. The 
solution is to use a private header - one that is #included into all the 
sources of that module, but is not available to "user" source files.

-- 
Richard Heathfield
Email: rjh at cpax dot org dot uk
"Usenet is a strange place" - dmr 29 July 1999
Sig line 4 vacant - apply within

[toc] | [prev] | [next] | [standalone]

#103764

On Sun, 12 Feb 2017 20:58:27 +0000
Richard Heathfield <rjh@cpax.org.uk> wrote:

> Similarly, headers can be shared amongst source files in a module, 
> without necessarily being published as part of the binary distribution.

You can do the same with source inclusion without mixing private and public headers in the same place which bring a bit of confusion in your source tree.

Here an example of source tree I use:

/project/src     <- source files
        /include <- headers
        /bin     <- binaries
        /lib     <- libraries
        /tmp     <- object files
        /doc     <- documentation

I usually split /src with directories for each set of related functions (library) such as:

/src/set1        
    /...
    /setk

And sometimes I share code with /src/common for any set.

I also split complex functions in small functions with the rule, at most one function per source file with include gard for source inclusion if the function should not be public. At last I only compile public code.

[toc] | [prev] | [next] | [standalone]

#103770

On 12/02/17 22:06, GOTHIER Nathan wrote:
> On Sun, 12 Feb 2017 20:58:27 +0000 Richard Heathfield
> <rjh@cpax.org.uk> wrote:
>
>> Similarly, headers can be shared amongst source files in a module,
>>  without necessarily being published as part of the binary
>> distribution.
>
> You can do the same with source inclusion without mixing private and
> public headers in the same place which bring a bit of confusion in
> your source tree.

Confusion? I haven't found it to be so.

>
> Here an example of source tree I use:
>
> /project/src     <- source files /include <- headers /bin     <-
> binaries /lib     <- libraries /tmp     <- object files /doc     <-
> documentation
>
> I usually split /src with directories


...Whoa! And you say private headers are confusing?

-- 
Richard Heathfield
Email: rjh at cpax dot org dot uk
"Usenet is a strange place" - dmr 29 July 1999
Sig line 4 vacant - apply within

[toc] | [prev] | [next] | [standalone]

#103773

On Mon, 13 Feb 2017 06:00:50 +0000
Richard Heathfield <rjh@cpax.org.uk> wrote:

> ...Whoa! And you say private headers are confusing?

I know the source tree looks well defined instead of your header
bazaar. :-)

[toc] | [prev] | [next] | [standalone]

#103771

On 02/13/17 09:38 AM, GOTHIER Nathan wrote:
> On Mon, 13 Feb 2017 08:10:36 +1300
> Ian Collins <ian-news@hotmail.com> wrote:
>
>> On 02/13/17 08:03 AM, GOTHIER Nathan wrote:
>>
>> Please limit your line length!
>>
>>> Hello everybody,
>>>
>>> After reading many headers in different C projects, I realized the
>>> fact that there are many private code (macros, typedefs, ...)
>>> included in headers that makes difficult to distinguish what is
>>> useful for the end user.
>>>
>>> Since I consider headers as some kind of minimal documentation for C
>>> programmers, I put every private code in source files and only public
>>> code in headers. Although it could lead sometimes to put all
>>> unrelated private code in one common source file with an include
>>> guard.
>>>
>>> What do you think about this practice?
>>
>> Why don't you just use a private header?
>
> Do you compile private headers? For me appending "private" to
> "header"  looks weird... since we usually make public access to private
 > code with headers. ;-)

Please limit your line length!

Private headers aren't directly compiled, they are included.

-- 
Ian

[toc] | [prev] | [next] | [standalone]

#103774

On Mon, 13 Feb 2017 19:07:12 +1300
Ian Collins <ian-news@hotmail.com> wrote:

> Please limit your line length!

Sorry, I am not very efficient with Sylpheed until I discovered the right
button to limit the line length without breaking words. This message should be
limited to 80 characters by line if I am not too bad. :-P

Sometimes I may forget to limit the length since I prefer to do it manually at
the end of the message in order to avoid manual reformatting.

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.c

csiph-web