[Development] Using '#pragma once' instead of include guards?

[apoenitz]

On Tue, Mar 05, 2024 at 10:43:50AM +0000, Volker Hilsheimer via Development wrote:
> >  On 4 Mar 2024, at 15:56, Kai Köhne via Development
> >  <development at qt-project.org> wrote:
> 
> >  Hi Marc,
> >  I've nothing against using '#pragma once' for private/internal headers.
> >  But you said you mainly want to have this to differentiate between
> >  different types of headers. If this is the motivation, I think we can
> >  make this differentiation even more explicit. For instance, public
> >  headers could get a
> >    // This header is part of the public Qt API.
> >  comment. Much like the 'We mean it', or 'pragma once', syncqt could
> >  enforce this for public headers, and error out if it's used for
> >  non-public ones.
> >  Kai
> 
>    I think the challenge then is again how syncqt can know what a public
>    header is. How does syncqt know that src/plugins/**/*.h headers are not
>    public headers? They look like public headers, except for the “plugins”
>    in the path. How do we, on a build system level, distinguish between
>    “private installed” and “private non-installed” headers?

Opt-in by a specific comment 

  "// This is a public/private/... header"

sounds like an option to me.

>    In the end, syncqt can ideally rely on an explicit decision that has
>    become manifest through an easily recognizable pattern in each header
>    file. Whether we replace include guards with #pragma in all non-public
>    headers, or tag all public headers with a comment doesn’t really matter
>    all that much, does it?
> 
>    But given that we have the “We mean it” comment already for _p.h
>    headers, would it not be more consistent if we simply add that comment
>    to all non-public headers (no matter their file path, and no matter
>    whether the header is installed or not)? That comment makes the
>    usability of the declarations in the header obvious to the reader,
>    without having to know the rules.
> 
>    We have agreed that for some headers we allow use of #pragma, but
>    taking myself as a reference, I doubt that it’s obvious to everyone
>    which headers are installed, and when it’s allowed to use #pragma, and
>    when it’s mandatory to use #pragma. Perhaps adding the “We mean it”
>    comment to all headers not declaring public API is less obscure? The
>    question is if and how we can use syncqt to enforce this reliably.

Even if we find out that there's a 1:1 relation between "#pragma once" and
private headers I also think it's worthwhile to make that explicit.

Andre'