Coding Convention: Sorting Order of Includes?

[Sebastian Huber]

On 08/01/2020 20:09, Gedare Bloom wrote:
> On Wed, Jan 8, 2020 at 9:33 AM Joel Sherrill <joel at rtems.org> wrote:
>>
>>
>>
>> On Wed, Jan 8, 2020 at 8:03 AM Sebastian Huber <sebastian.huber at embedded-brains.de> wrote:
>>>
>>> On 03/01/2020 17:52, Gedare Bloom wrote:
>>>> Hello all,
>>>>
>>>> Vijay noted in another thread that:
>>>> "For RTEMS, I don't see any preference mentioned in the docs for the
>>>> order or includes:
>>>> https://docs.rtems.org/branches/master/eng/coding-conventions.html
>>>>
>>>> In libbsd, however, the FreeBSD style guide is followed which has a
>>>> preference for the order of header includes:
>>>> https://www.freebsd.org/cgi/man.cgi?query=style&apropos=0&sektion=9"
>>>>
>>>> Should we consider any rules? I would suspect that at least ordering
>>>> by API layering could be helpful. Lexical sorting is nice but probably
>>>> there will be some exceptions based on dependencies.
>>>
>>> I would use the Google rule:
>>>
>>> https://google.github.io/styleguide/cppguide.html#Names_and_Order_of_Includes
>>>
>>> It is compatible to the FreeBSD style (except the include related header
>>> first).
>>
>>
>> FWIW I don't like how they worded that. I think they mean the public header files.
>> Related would include private header files which are grouped later. But the rationale
>> makes sense as long as there isn't a conditional for "inside the package" which covers
>> up issues.
>>
>> There is also the issue of defining conditionals like POSIX level, GNU misc,
>> IN_KERNEL, etc.. I try to do that before any includes.
>>
>> --joel
>>
> The 'related header' raises for me one question, which is how to treat
> *impl.h headers.
> 
> In general the style rules I have seen go from "general to specific"
> ordering. As mentioned, the Google guide makes one exception to
> include "related" header, which appears to be singular "the related
> header" implies to me (in agreement with Joel) the header that defines
> the functions of this source file.  I suspect there would be no such
> "related header" in a header file, except maybe we would consider our
> *impl.h header to be a "related header" of a public header file?  That
> would be one issue to clarify before moving forward with a proposal on
> header file order.

Yes, I would consider XZY.h a related header to XYZimpl.h and include 
XYZ.h here first.  In general the "related header" is only meaningful 
for includes done in implementation source files (*.c and *.cc).

> 
> Once we decide whether to use the 'related header' or not, I think we
> can define the rules following the FreeBSD/Google style and
> Sebastian's suggestion. We have the somewhat odd position of having
> both "kernel" (supercore) includes as well as userspace includes
> (C/C++ libs), so we can't just point to either of those style guides
> and  say "use it". A bit of writing has to be done :)

The "kernel" includes are "8. Your project's .h files." from my point of 
view.

Yes, some writing is necessary.

-- 
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 189 47 41-16
Fax     : +49 89 189 47 41-09
E-Mail  : sebastian.huber at embedded-brains.de
PGP     : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.