1

I am reading through an embedded C standard book and I noticed the following:

No header file shall contain an #include statement

What should I do with function declarations that have non-standard types?

example: void function(some_funky_type x);

Jonathon Reinhart
  • 132,704
  • 33
  • 254
  • 328
Ghazy
  • 19
  • 3
  • You should include them in the header file. That statement is nonsense. I'm working on a embeded system with a SIL2 standard and we sure do have include statements in the header files. – Fredrik Jan 18 '17 at 22:30
  • What's wrong with includes on an embedded system? The standard has its list of headers that must appear on all conforming implementations for freestanding environments. – DeiDei Jan 18 '17 at 22:30
  • When was the book first published? – user3386109 Jan 18 '17 at 22:45
  • 2
    The [Indian Hill C Style and Coding Standards](http://www.literateprogramming.com/indhill-annot.pdf) (circa 1997) promulgated this theory. It was produced by well-respected people. The general consensus has changed and that guideline is no longer accepted in modern practice. – Jonathan Leffler Jan 18 '17 at 23:06
  • What code standard do guys recommend for embedded C? This one was suppose to be a good one. – Ghazy Jan 19 '17 at 15:14
  • @user3386109 it was published in 2008 – Ghazy Jan 19 '17 at 20:27
  • It's really sad that there's such a flood of crap programming books on the market. Just today someone asked me if I could recommend any good C programming books for beginners... all I could say was "I can give you anti-recommendations". – Lundin Jan 20 '17 at 12:35
  • @Ismailghazy I would strongly recommend MISRA-C:2012. It is a very professional document written by actual experts, rather than wannabe-experts. – Lundin Jan 20 '17 at 12:55
  • Specifying the book in question (title, author, ISBN, publication date, and/or direct link for example) would give context to your question. You may be misinterpreting the directive or reporting it out of context, or you may be reading trash. If the "book" was free and antique, you should be cautious - there may be a reason that it is out of print! "supposed to be a good one" by whom? Citation! Citation! Citation! Published in eBook form in 2008 or 1st print edition from 2008? Why so secretive about what you are reading? How do you expect to get a measured answer without revealing!? – Clifford Jan 20 '17 at 13:30
  • Get a better book. Even the standard headers include other standard headers. – too honest for this site Jan 20 '17 at 13:52
  • @Clifford I did not not want to tarnish someones image. The book in question is "embedded c coding standard" by Micheal Barr. I have seen useful information on Barr group's website. I sent them a message to see what their reasoning was for that rule. the have the same rules on their website and I am guessing it is up to date with what they follow. http://barrgroup.com/Embedded-Systems/Books/Embedded-C-Coding-Standard/Introduction – Ghazy Jan 20 '17 at 13:58
  • You could tarnish his image only if you misrepresented what he'd written or took it out of context (which is why the context is important). If you truly and accurately report what he has stated in its correct context, then it is not *you* tarnishing his reputation - anyone can read his book and come to a view. A good coding standard will include with any directive, its justification, what potential problem it is trying to solve and possibly circumstances where it may not apply and may be deviated from. That (if present) is the context missing from here. – Clifford Jan 20 '17 at 15:29
  • @Ismailghazy Michael Barr usually knows what he is talking about. For example he gives some sound advice about this very topic in his blog [here](http://embeddedgurus.com/barr-code/2010/11/what-belongs-in-a-c-h-header-file/). However, that particular rule in his coding standard seems weird indeed. [It can be found here](http://barrgroup.com/Embedded-Systems/Books/Embedded-C-Coding-Standard/Module-Rules/Header-Files). All other rules on that page are sound, so I'm wondering what the rationale behind this is. As it stands, it does indeed make no sense. – Lundin Jan 20 '17 at 15:32
  • On the face of it however, the rule makes little sense. When including an interface you should not have to know what interfaces it in turn requires; that will lead to many confusing errors and require you to include headers (by trial and error) that are not directly relevant to your code. Your code may work because you have included something that your code needed but later remove, or it may work because your includes are in a specific order and reordering could break the code. A header should include everything it needs to resolve any symbol it uses. – Clifford Jan 20 '17 at 15:35
  • The "reasoning" for Rules 4.2 a to d make clear the intent - to not expose unnecessary interfaces , but adhering 4.2d just causes a worse problem of missing *necessary* interfaces. If all the other rules are followed any perceived problem that 4.2d attempts to solve is lessened in any case. If you don't include necessary interfaces there, you will have to include or declare then elsewhere and in the correct order - with no means of knowing what the order is. For reusable or third-party library code it is impractical and undesirable to follow this rule. – Clifford Jan 20 '17 at 15:47

2 Answers2

8

Throw that book away; it is absolute garbage. In fact, you should burn it, to make sure no other poor soul ever picks it up.

Header files should absolutely include all of the header files necessary for them to be self-sufficient. There is nothing worse than trying to carefully massage the order of your #include statements to be sure that the types needed by one are already defined before it is included.

Jonathon Reinhart
  • 132,704
  • 33
  • 254
  • 328
  • 1
    Ok. I agree with this. That is what I usually do and then I read this and thought I was making a mistake. Perhaps it was easier with older tools to not have headers within headers. Also, its an e book I'll have to Shift+Delete – Ghazy Jan 19 '17 at 15:58
4

This is a stupid and counterproductive rule for precisely the reason you identified. The alternative is for every .c file to include all of the .h files that a subsequently included header will require. You can imagine that if you introduce a new dependency in a commonly included header that you will now have to update every C file that includes that header.

Dave
  • 885
  • 2
  • 10
  • 20