Hacker News Reader

I would strongly recommend that people new to C and reading this comment do not follow this advice. It might have made sense back when it was written but it's not how modern C is typically written, and it would be very annoying for modern C coders to put up with these shenanigans.

Multiple inclusions are hardly a problem nowadays, with header guards it means that subsequent inclusions won't actually include anything and the performance impact is fairly negligible the vast majority of the time. C compilers are pretty damn fast these days and in my experience it's the optimization pass that slows things down the most, not parsing includes.

Also in general I tend to take what Rob Pike says with a grain of salt, he's a very smart guy and he definitely says interesting things but he has weird idiosyncracies. He's definitely worth listening to, but I wouldn't follow his advice blindly. See his weird take about how "syntax highlighting is juvenile" for instance.

Headers not including headers is still good advice, it's not so much about fast compiles (at first at least while a project is small), but about not letting header inclusions grow out of control (see almost every C++ project with more than a few hundred source files, it's almost impossible to clean up unused headers, and even when that happens - after a few weeks it's back to the old mess).

See here for a relatively recent take on this:

https://ourmachinery.com/post/physical-design/

The only practical issue with "out of control" includes is still compilation time though, especially if modifying a single file causes many other files to rebuild because they include it directly or indirectly. Beyond that I really don't care about it, I don't usually bother to micromanage my #includes, I don't really see the point.

Beyond that I think that very complicated include graphs are usually a sign that there's an architectural problem with the application, forbidding includes within includes treats the symptom, not really the core of the issue.

As a quick example of some code I wrote not long ago: I have a microcontroller communicating with an external chip over a serial link using a custom protocol. I have a "serial.h" file that describes the API to send and receive serial messages, then a "protocol.h" that implements the higher level protocol. protocol.h includes serial.h since it uses it as a lower layer, it's effectively a dependency. I don't really think it's a problem.

So I'm not really sure that it makes a lot of sense to forbid includes within includes as a rule of thumb. I guess if I was to make a rule it would be "include trees are fine, include graphs are bad"? As in, there shouldn't be cycles in the include graph?

Yeah - so layer-lawyer would argue that the only thing that needs to talk to serial.h would be the protocol - but, in the real world of deployments that actually work in the field, it's often the case that layer lawyers get in the the way, and being able to bypass the protocol to talk directly to the phy is a thing - which means you end up including the phy at multiple places.

Purity vs Practicality.

Headers not including other headers is a great thing IMO.

If you’re coming into a code base with new eyes there’s less confusion as to where things came from.

Of course if you’re reading code - ctags, and cscope are invaluable. I’ve yet to use this fancy new LSP stuff but it seems popular.

Convenience headers can be ok occasionally but it kind of runs in the face of writing modular software at times.

Syntax highlighting has caught a few mistakes for me in the past but I do think it’s kind of a crutch.

Not including headers in header files can be confusing.

Say you maintain a library (lib1.h) that exports an API that takes in an argument defined in lib2.h.

If you do not include lib2.h in lib1.h, then the users of your API need to include lib2.h before lib1.h in every source file and header. With a larger number of dependencies, this can become unwieldy for users.

In addition, future maintainers of your library may also find it confusing why things break when includes are reordered.

Most modern C compilers are aware of include guards: if they notice that the _entire_ file is enclosed in include guards, they won't read it a second time.

I haven't opened up my C compiler to verify this, but even for ancient compilers that would be a non-issue, as they see only what the preprocessor hands them. Re-reading (i.e. parsing by the preprocessor) an include file isn't so bad either, as it is already cached.

I find this focus on compilation speed curious. At my last workplace a full built took a good share of the day (!) and was typically done overnight. Building during the daytime was discouraged, as it happened on our workstations, slowing down everything else. We found ways to cope, chiefly learning which subsets are autarkic, i.e. finding the least general Makefile which when invoked would catch your recent changes and wouldn't traverse too much of the tree. Not ideal, but workable.

> full built took a good share of the day

Yikes Was this with/out some sort of cluster support?

Which language?

Is this due to legacy practices, or is it simply a difficult build?

I am asking because i am involved with a parallel build project. and often there is plenty low hanging fruits

> Yikes Was this with/out some sort of cluster support?

Each developer built on their own workstation. We meant to look into built-cluster, but we never got around to it.

> Which language?

C++ mostly old style, some C++11, quite a bit of template programming (but I haven't seen anything too fancy).

> Is this due to legacy practices, or is it simply a difficult build?

It sure was an old code base, not sure what you mean by legacy practices (but that might make it a yes ;-} Not sure either, what would make it difficult, but there were C++ templates and it was fairly large (sum of resulting object files in the order of a few hundred MiB).

That breaks undefs before includes.

Well yeah. If you make normal, idiomatic use of include guards, compilers will be able to apply this optimization. If you do weird stuff, they'll be forced to re-read the file.

https://gcc.gnu.org/onlinedocs/cppinternals/Guard-Macros.htm...

That is a major usability setback. It gets worse when headers A and B both require header C. Let's say your source already includes A and C and you want to add B. Now you need to manually read through the comments to understand where exactly in the include list you need to plug it.

This will become completely unmanageable once your include count surpasses 20-something, which is normal for large projects.

As with much of Pike's advice, it's worth remembering where it comes from: Unix, specifically AT&T-style Unix (and later Plan 9), where a fairly disciplined (programming-wise, at least :P) team of very good, and oftentimes very experienced developers wrote a lot of small, interconnecting utilities.

If your whole source code is written in that manner, and written by people who write code in that manner, this advice is easy to follow.

On the other hand there aren't many files in the Plan 9 source tree that are longer than, what, 3,000 lines? 4,000? Attempting to shoehorn that, and many other well-intended nuggets of wisdom from the Unix 'heritage", into your average commercial codebase, with dozens of third-party libraries and whatnot, is unworkable (I know, I tried).

Some programming advice pearls translate well into any project. "Avoid gratuitous comments like "increment i", use comments to explain the reasoning behind functionality, not describe what the source code already adequately describes" can be applied on any source tree, starting at any point. But some of them -- such as this one -- only work if you write and organize your code in a particular way.

FWIW, I think that this bit of advice was useful back when Pike wrote it, in the age of slow, buggy C compilers (although some would argue we're still in that era!) munching code off of network-mounted drives. Nowadays, not so much -- I think it has readability advantages but I doubt the performance gain (if any is left) is worth the extra programmers' effort. I like to follow it when I'm writing small utilities but I don't really fuss about it for larger projects, and I've never been curious to see how fast it is. I believe (but never measured it, so take it with a grain of salt!) that it's one of those things that 30+ years of computer systems evolution (in the biological sense -- "advancement" is probably too strong a word) has made obsolete.

Usability is easy to fix. Replace comment with #pragma or better list dependencies in a separate file (like gemspec). Add #require keyword which resolves order automatically.

That's advice from February 21, 1989. They've implemented OS and some GUI applications, for example acme text editor [1]. Maybe it is not that hard.

[1] https://github.com/brho/plan9/blob/master/sys/src/cmd/acme/a...

I think that's (a big part) of the whole point: splitting a project into too many small headers which depend on each other is bad. Including headers into headers just hides the problem, but it's still there under the hood and grows worse the bigger the project becomes until it's too late to do anything about it. That how you get hours-long compile times in large C++ projects.

Instead use few big headers, for instance one public-interface header per system/module which only contains declarations (no inline or template code), and at most one private header for each module (or better none at all). Then keep the dependency tree between modules/systems as flat as possible.

This is especially important for large projects.

The preprocessor can be expected to read files and scan to the corresponding #endif very fast. Reading from cache is also very fast. C++ compilation bogs down when templates are involved. You want to split those (in a way which makes sense to the human reader), so that only the ones needed for a given compilation unit are instantiated. Further the link stage, which is difficult to parallize, is a bottleneck.

It's not just about compile speed, but also about staying sane while working on the project ;)

> Now you need to manually read through

C already has similar problems that are worse. For any given function used in a program, you have no guarantee that you can locate where that function is implemented in a straightforward way. In the worst cases, you have to resort to using dumb hacks like ctags or a project-wide recursive grep. It makes it hard to read any given program in the Knuthian way—laid up in bed with a printout to study how it works.

(Go has the same problem. When I started seriously looking at Go, I was surprised that it copied C here, given the strong influence from Oberon.)

This sounds like something that can be solved by a separate tool (similar to rcorder that determines the order in which to execute rc files in BSD systems based on their dependency specifications) one can plug into the build process.

Or use a language witn normal ʼimportʼ support.

He's not wrong per se but this shows how utterly broken C is. And macros are a "bandage" that make the problem worse.

> include files should never include include files

Cool, there are two possible outtakes to this:

1) Why aren't include files generated automatically from C files then? (If you can't include anything this means they shouldn't have no "code", so they can't call anything, so they can't include anything or reference anything else)

2) Why aren't they a compilation target? (yes I know modern GCC allows you to do that) but why doesn't C specify a binary representation for them.

He addressed performance issue. Just what parent asked — separate interface and implementation.

Looks like you ask "why convention, not restriction?" It solved their problems while maintaining interoperation with UNIX world [1]. If convention is not enough for you, you may define format and tooling.

[1] http://doc.cat-v.org/plan_9/4th_edition/papers/ape

Because ISO doesn't force language implementers to do such tooling, which is also why there is UB to start with.

Agree with the first part, but I’m not sure where you’re going with the second.

The unwillingness to standardise specific language features back in the 80s, during C89, because they would break pseudo compatible K&R compilers like Small-C, or force vendors of now long dead platforms, to actually spend a little more effort improving their toolchains.

A variant of this is to mandate that every header #define a documented symbol, and then have a #ifndef guard for this around the inclusion of the header.

The standard practice of putting the ifndef guard inside each header is specifically optimized by compilers, though I don't recall where I read that.

I don't know why this is downvoted. This is exactly how it is.

The first time the compiler reads the include file, it remembers where the corresponding #endif is for each #if. The next time the file is included, the compiler can skip over the whole included file. There is no performance advantage from outsourcing the conditional to every including location.

Putting an ifndef guard at the location where the file located is not workable. It's terrible boilerplate. To the relatively simple '#include <A.h>' another variable that must be synchronized with dependencies gets added. Plus 2-3 lines for the conditional. At each including location.

IIRC, this is documented in the CPP part of the GCC manual. Whenever a header file is completely enclosed in a ifndef guard, and that guard is still defined, it will skip the whole file.

Another option is "#pragma once"; it's non-standard, but every popular C compiler (even MSVC) understands it, and has the advantage that there's no risk of accidentally using the same include guard for more than one header file.

Windows compilers were the first to have it, naturally MSVC understands it.

All production compilers now support `#pragma once`, so the traditional `#include` guard is almost totally obsolete.

The only plausible exceptions are in proprietary compilers for microcontroller SDKs.

I very rarely encounter #pragma once in the wild personally, and I still always use old school #ifndef guards myself. I can't really see a reason to change: it's not a huge amount of typing, it works everywhere, it's very explicit and not magical.

For instance out of the top of my head I don't remember how #pragma once decides what constitutes the same include file. If you have symbolic links, or absolute and relative paths for instance, how does it work? I'm sure I can find the answer in the compiler's documentation, but with #ifndef I don't even have to, it's obvious what's going to happen.

I would personally argue that old school guards should be preferred because of this and the fact that they're standard, but I don't feel super strongly about it.

I've seen terrible bugs in the past where there were multiple incompatible versions of a header file in a codebase, but nobody noticed because both headers used the same guard variable name, so the header that was included first always won.

Yes, this is the usual failure mode. It happens quite often, because nothing checks for unique or correct guard names.

Failing to switch to `#pragma once` when it becomes permissible is reckless and irresponsible.

I'd think it would be much easier for a preprocessor to determine that it is done with a file, once it encounter that pragma, instead of having to scan for the corresponding #endif (not sure if it'll dare to scan from the back and hope that all #if/#ifdef, #endif pairs match or whether it diligently checks those every time).

Wouldn't it be as simple as maintaining a bloom filter containing the absolute paths of every included file encountered so far? Whenever you encounter #pragma once you check if the file is already present in the bloom filter and return early if it is. If it's a new file you add the file name to the bloom filter and continue processing.

It probably even more memory efficient (albeit insignificant in the grand scheme of compiler memory usage) for the compiler to just maintain the bloom filter and not have to deal with hundreds of otherwise unused preprocessor symbols, one per include file.

The typical argument against pragma once is that it's unclear what should happen if two different hard link paths are used to include a file with the same inode (along with similar situations on Windows or with files on network drives). That is to say, in general, there is no consistent and portable "true" absolute path that uniquely identifies file(s) as conceptually having the same underlying storage.

In practice, I have never actually seen a problem arise. The most likely real trigger would probably be a mix of including a library through a path that indicates a specific version and including it through a path that uses a "latest stable" link. That is already fragile and asking for trouble, though.

Bloom filter can have false positives.

You may imagine that you are helping the compiler avoid error, but the fact is that real compilers, when they encounter `#include` guards, translate therm implicitly to `#pragma once`, and move on. The compiler is better at it than you are.

Meanwhile, you are exposing yourself to subtle bugs resulting from multiple headers that define the same guard name, as noted nearby. So, your imagined virtue is folly.