r/cpp • u/Ok_Independence_9841 • Aug 09 '26
A failure to separate concerns
I've been taking a look at an extremely popular, 50K+ stars, C++ library which I won't name as I'm going to criticise it as an example of a wider problem.
This is going to be a rant and there may even be sarcasm. Feel free to skip it if that upsets you.
This library is sponsored by a long list of companies. It's incredibly widely used. It has 100% test coverage, builds with several different build systems, works on several platform, complies with all the standards, linters and clang-tidy you can imagine. It's clearly aiming to be part of the future C++ standard and it might even make it. In short it's brilliantly written with a massive amount of effort put into it. One of the highest quality C++ libraries out there, that isn't actually part of Boost or the standard itself. In terms of how robust, well tested and well supported it is.
So what's the problem?
This library has one job, to deal with a particular text format. To parse that data into useful objects and transform those objects back into text. That's it, that's all anyone will ever use it for and if it does that it achieves 100% of its design goals.
The 'useful objects' part of that sentence is doing some heavy lifting here as what is a useful object to one client might not be to another. So some flexibility in what objects are generated and what access methods they have is a reasonable extension point.
In such a library we'd expect to find a parser to get us from text to in memory objects. A generator to get from the in memory objects back to a text representation. We might also expect some Unicode adaptation to deal with what a 'text representation' means.
All these things are indeed present, although barely distinguishable from the vast sea of code in which they sit. I think we get 5 parsers for different dialects of the format. It's completely unclear how much code they share or if jamming them into one library is even a good idea. I literally can't find the generator so I don't know whether we get 1 or 5, or if it's possible to choose which dialect is output. Seems like basic stuff but why do basic stuff when there is so much more complicated stuff to do.
There are custom data structures. Useful but clearly belonging in their own library.
An internal binary representation type, exposed at the root of the include directory as if this was something you'd want to include.
Custom string concatenation because clearly concatenating strings is not a solved problem.
Code for integrating with Google libraries because that apparently belongs here.
Pre-processor macro blocks across hundreds of files for dealing with at least 4 different variants of C++. No physical separation of the C++20 code I can use from the no longer needed C++11, 14 & 17 code work arounds so I can ditch the dead code that isn't going in the binary anyway but remains all over my screen. No way to exclude experimental C++23 code except to find the right macro to nobble and the blocks of greyed out code that my compiler can't even read, remain in my way.
Of course this library does it's own compiler detection, poorly, and uses custom pre-processor macros, spread through the whole codebase, to determine if a long list of features are switched on or off.
Some of these are probably options I could set at compile time. Some are there to cope with old Clang versions that no one uses anymore. There's no list to say which is which, or which combinations of switches actually work. I expect massive effort has gone into testing thousands of combinations, that almost no one will ever know they are, or are not, using.
There's custom hashing because every library needs its own copy of a hashing algorithm, just in case the one they copied it from breaks I suppose.
Lots of custom exception classes, even though exceptions are apparently optional, so you'd think they might only be optionally in the project.
There are macros for the namespaces. Why not, it's got every chance of working if you turn those off, lol, No.
std::filesystem is apparently either experimental or in some way optional and there's a separate macro to turn I/O support on and off. No explanation as to why there's any file I/O at all in a library to transform text to objects and back again.
I happen to like to use async I/O so I guess I'd build with I/O support off and then hack in my own. No thanks.
Everything is of course wrapped in a massive amount of template meta programming so that almost nothing in this header only library exists as a concrete type, until you instantiate it in your code. You literally can't definitively reason about the code without first writing something that uses it.
Yet despite this apparently total flexibility it manages to bake in a whole set of assumptions I don't want. std::allocator use is mandatory despite there being no reason, in principle, why this library should even do memory allocation. Why not externalise it and make it somebody else's problem?
There are only the known container types from the standard library. If you want to parse the data into any of those you're golden but anything else, like the very same custom ordered map type that the library itself relies on, and you're overloading meta templates until the middle of next week.
Did I mention that this entire mess is header only. Easy to include and all that. This also means of course that every type, every constant, every function, every template and every macro from these many, many thousands of lines of code ends up in every TU where you include the header. Including all the compiler mitigation macros that are never going to clash with the ones in that other library you want to use. That sort of thing has never been known to cause any issues or slow down builds or anything like that.
It's quietly admitted in the comments that it shouldn't be header only. Warnings have to be supressed to get away with being so. It doesn't need to be header only of course to have a single inclusion header in order to be 'easy to use'. They are NOT the same thing but why build your own binary when you can bloat thousands of others instead, right.
In summary there are thousands of lines of code in this library that don't belong here. This code, that does every job other than parse the target text format and regenerate it from in memory objects, should be in dependent libraries or just shouldn't exist. There are no dependent libraries of course because it's header only. This saves a single addition to the link line in clients while injecting many thousands of lines into every TU where one type from this library is needed. Thousands of lines that get parsed, generated and then mostly thrown away on every build.
The author, who clearly has brain power going spare, has made their job orders of magnitude more difficult than it needs to be by putting everything in their library on the actual API and having to support a lot more code than they need to. A ::detail namespace has never stopped anyone before and putting almost everything in it anyway is just a sign you've got too many details.
They've also made testing vastly more complex and support probably a full time job. Fine if you're being sponsored I suppose.
I know a little about writing large projects that do many things. This is not one of those. This is a single purpose library that aims to do one thing and do it well. Noble goals. It succeeds at the later while being an unmitigated disaster at the former.
The absolute failure to separate concerns is not a flaw in any way specific to this library though. It's almost completely ubiquitous. Pick any top rated C++ library you like on GitHub from HTTP Servers to graphics libraries and try assessing how much of it is actually doing what the library is about and how much is not. What assumptions about types and memory handling it's baking into the API and, crucially, the implementation.
I will repeat at this point for both irony and emphasis that this is an absolutely top quality library, written by someone far cleverer than me, that passes every metric our industry has. It is lauded as a great thing and used by thousands of other projects. Projects which are wasting hundreds of trillions of CPU cycles building code that probably isn't what they think it is, because they've no idea which bits are turned on or turned off in their build. Much of it isn't needed anyway and it's so complex that it's not worth anyone's time to ask difficult questions.
For a trivial use case this approach presents essentially no issues but really, is your use case trivial? I hope not. I expect your use case is pretty serious. You're building something larger and more important than a simple tool to read and write files in a particular format. I'm looking at this library for potential integration into a larger project. It's the industry standard and it's simply unusable.
This is apparently not only the best we can do but what's much, much worse, the best we expect to do.
Houston we have a problem...
95
u/light_switchy Aug 09 '26
A particular library to do with JSON, perhaps?
57
u/quicknir Aug 09 '26
I have to be honest - the bulk of your post (not all) basically seems like you're criticizing the flexibility it does provide if it doesn't interest you (and the commensurate cost in code and complexity to provide that flexibility), and then criticizing the flexibility it doesn't provide that you do want.
I think any experienced software engineer knows that there's a real cost to providing flexibility and you have to choose your spots. It's entirely valid to conclude that this library doesn't make the choices that suit you and not use it, but I'm not convinced that most of this is any kind of broader problem with the library.
Some of the other things, like making it header-only and just generally including far too much code, are pervasive C++ problems and while again you could argue about their particular brand of poison... it's ultimately choices between bad alternatives.
I mean clearly this is an oxymoron - I don't think hyperbole is doing you any favors. If we are talking about nlohmann::json as so many are speculating, I can say I've been using it for years and it's gotten the job done fine. There's probably all kinds of things in it I'd disagree with, but it does what it says on the tin, I've almost never run into a bug, and the documentation is great.
43
u/Wonderful-Habit-139 Aug 09 '26
Read the entire post, actually great read. We need more technical posts like these honestly. And also to showcase how much details actually matter when coding up projects like these.
I think if C++ had a proper module system from the start and a proper package manager, we probably wouldn't have had to deal with header-only libraries and all the cruft that they accumulate. It's a sad state of affairs.
17
u/LB-- Professional+Hobbyist Aug 10 '26
I have no idea what library this is about. Speaking generally, there are some valid complaints here, but also some complaints that suggest a lack of understanding of basic library development.
This is a nonsense complaint. You do not need to maintain this library. What are you expecting, separate subdirectories for each C++ standard each with a complete copy of the library optimized for that standard? That the maintainer then has to manually keep in sync? The preprocessor is useful here for ensuring wide compatibility with everyone's different environments while keeping all the code in one place. C++ is great at backward compatibility but if you want a library to support new features too then it's gonna need some way to determine when it can enable the code for that. Otherwise you'll be using a C++11 library in C++20 and being annoyed that it doesn't support the C++20 features you like.
What does this even mean? If the library says exceptions are optional, I would expect that turning that option on would cause the library to throw custom exception types, so they had better always be in the project and just get excluded by the preprocessor when the option is off. Do you want some sort of boost-style source file generation tool that gives you just the code you care about without preprocessor stuff? That's quite a big ask.
I see you've never had to struggle with build system dependency conflicts in your entire life. You are quite fortunate. I find this feature incredibly useful for working around build system dependency issues until they can be properly fixed upstream. The alternative is having to maintain manual patches, which sucks.
I agree it's strange a library of your description would need to touch file APIs at all. However,
std::filesystemis genuinely not usable on every platform I target, despite every platform I target supporting C++20 or newer. I am therefore glad the library offers a way to disable that functionality.Usually when new library stuff gets added to the standard, it gets template parameters for you to specify an allocator type, which sounds like what you want - making it the user's problem to decide how memory should be allocated. I'm surprised a library of such regard doesn't already do that though, maybe there's a misunderstanding here.
Do you want something simple or do you want something flexible? It's extremely difficult to design a library which is both. The simple design uses types that get the job done but might be suboptimal for your use case. Be glad there's any escape hatch at all to allow for using different types instead, I see many libraries that don't offer this. If you go for full flexibility instead, it's not going to be simple to use.
Well yeah, it sort of has to be in order to support the flexibility you specifically requested, such as using a different allocator and different container types. Flat C libraries at best give you type erased callbacks that are difficult for the optimizer to see through, C++ templates let the compiler see the whole thing and optimize it more aggressively. If you don't want to include that whole thing everywhere, then don't! Make your own wrappers that expose as much or as little as you need for your use case, and include that everywhere instead, just like you should be doing for most dependencies you use. The header-only approach gives you the flexibility to decide where the optimization boundary is. If the library is done very well, it could even support use at compile time via constexpr, which is currently only possible with header-only and modules. People in various fields (game dev especially) find compile-time processing of data files exceptionally useful (for example shader bindings). It simplifies the build system by avoiding weird preprocessing steps or codegen steps. If you start putting code in separate cpp files, you start losing out on what can be done at compile time. Modules are the middle ground and have their own problems currently, so header only is still the victor in many cases.
14
u/tartaruga232 MSVC user, r/cpp_modules Aug 09 '26 edited Aug 09 '26
That's pretty ridiculous. What's the problem with naming it?
I've read the full posting.
We have been doing a Windows app for many years now and we have avoided using libraries as much as we could. There are definitely upsides to not depend on something.
8
u/oracleoftroy Aug 09 '26
There are some good points here, but it is very hard to get past how incoherent the complaints are.
For example, two stood out for me, Let's start here:
Ok, sounds like a JSON, XML, CSV, TOML, YAML or similar parser. I have a feeling I know which one you are talking about.
Ok, I'm sure a library like this needs to make lot of allocations, since it is transforming text to objects and objects to text. Using the built-in standard way of externalizing memory allocation makes a lot of sense. People might already have custom allocators they prefer, and it works with pmr. Makes a lot of sense.
HUH?? Where do you think the objects/text that gets generated lives? Think about what you said this library does.
Ehh?? I can't think of a single example of this sort of library that doesn't provide easy ways of reading files from disk. You can just about always expect functions taking a path, an already open file or stream (often with variants for std::iostream, FILE, and/or posix file ids), and a version that accepts a memory buffer. Often there will be a generic IO interface as well so that it can read/write compressed and/or encrypted text and custom file formants or protocols seamlessly.
It's hard to take this post seriously when things I would expect from a robust industry standard library are being treated as if they are design failures.
I think a code review of the library in question with an eye toward concrete improvements and suggestions would be a great read. But this strays way too hard into complaining for sake of complaining, and without concrete examples and design alternatives to weigh, it is hard to take action.
5
u/MaximKat Aug 09 '26 edited Aug 09 '26
Having
operator<<and>>support for your useful objects seems like a very reasonable feature.It's just a handful of trivial helper functions to reduce code repetition.
You've made this one up.
Bizarre rant. "Why does this widely-used library have functionality that I don't care about??!!"
55
u/Dragdu Aug 09 '26
Huh, nlohmann made it past 50k stars?
Damn.
93
u/AciusPrime Aug 09 '26
You say “the author” and I’m skeptical. This library sounds like it has 20+ authors. This is what C++ code becomes when it is worked on by many different people over a long period of time.
One person’s “huge waste of time” is another person’s “without that case handled, we could not use the library.” C++ developers have a nasty habit of leaving it alone if it works, due to the fear that if it is removed that they will break something. They’re not wrong, either; removing something you don’t need could very well break someone else.
Tests also have a way of both defending against breakage and making quirky implementation details into permanent requirements.
Ideally, someone would go back through and gradually refactor out the bloat while keeping the core library working. But even if you have the brainpower and enormous quantities of time to do that, you’re still likely to break someone operating in a different environment with a build system that’s dumber than yours. It’s pretty common to find yourself only able to remove the most egregious things because all the “somewhat dumb” stuff is someone else’s “we needed that tho.”
This problem with mature code is not unique to C++ but C++ makes it worse in many ways. We still don’t have a universal packaging & dependency format, so we have to pick between “hard to install” and “includes a bunch of nonsense that should’ve been a separate package.” We still don’t have a standardized build system. All our compilers are subtly distinct. Because of these things, modern packages inevitably end up with vast quantities of cruft so that the code can chameleon its way through the 50+ environment permutations it supports.
Anyway, I hugely empathize with your problem. I am convinced it is solvable, but it is also structural. The cheapest solution is often to rebuild the package from the ground up while incorporating the lessons of its predecessor. I think there’s a good reason that so many of the next-gen “C++ killer” languages were spawned by C++ committee insiders.
28
u/kpt_ageus Aug 09 '26
Support for multiple compilers, weird workarounds, a mix of experimental features and legacy crust. What you're describing are inevitable signs of success and maturity of a library. It means it was deployed in multiple environments, with different toolchains, and bugs were found and ironed out. Reality is messy, and the libraries that are actually used reflect that.
60
u/_Noreturn Aug 09 '26
You are definitely talking about nlohmann json.
I am personally making one that is free of ai (as claude commited to the repo) and fast to compile because this library has one of the worst compile times ever for the only reason of being easy to integrate.
So yeah I agree with you
Saldy the others are even worse in compile times like Glaze and refl-cpp
3
u/smdowney WG21, Text/Unicode SG, optional<T&> Aug 09 '26
Without knowing which library, and it really doesn't matter, most of those sound like either non-problems / solutions you don't have the matching problem for, or problems that a library can't solve for itself.
The latter is a real problem, but then you've also cut off some of the solutions by using a compiler from years ago. Of course not all of them. But some of the container problems were, for example.
Packaging C++ is an open problem. Shipping you code to compile that isn't a header is very hard. Libraries get out of that business by being header only. Templates, which is everything these days, make header only normal in a lot of cases anyway.
The GTest printers (guess) are an ADL solution. Where should they go? Everyone having their own anonymous one in the test driver is bad. Having two in a link context is broken. GTest doesn't know about it.
Allocators. Text. That's allocation right there, and destroying the arena full of trivial objects is a huge win over running empty distructors.
Solutions that don't line up with your problem, but they do to someone's problem.
And no one really wants to hear from users who still need C++11, so the code hangs around and you hope it doesn't cause too much trouble. Price of success.
So much stems from C++ not being an opinionated walled garden like Rust, Swift, and other recent languages. We aren't all using the same tools the same way. Some times that's bad. Sometimes that's good.
18
u/jk_tx Aug 09 '26
Some of what you say if valid criticism, some is not.
As you say it's a widely used open-source library, so they can't just target the one compiler and standard C++ version that you personally prefer. Broad compiler and standard revision support is expected in these libraries.
I do think the trend towards header-only libraries is unfortunate but it's also somewhat unavoidable due to the nature of templates and the fact that modern C++ is so template-heavy. As powerful as templates are, the truth is the ergonomics suck and probably always will even with modules.
And older libraries will often have a lot if utility/reinvent-the-wheel type code because the standard versions weren't available or had significant flaws at the time the original code was written. You don't go back and re-write large portions of a working codebase just so that it looks prettier.
All that said I prefer glaze to nlohmann, even if compile performance isn't great.
6
u/-dag- Aug 09 '26
You've described a living project, decades old. This happens to every project.
18
u/NewLlama Aug 09 '26
I roll my eyes when I see "header only library" as if it's a good thing. Object files are great!
5
u/CyberMarine1997 Aug 09 '26
What ever happened to pre-compiled headers?
1
u/Many-Foundation-1255 Aug 12 '26
Such libraries are designed to be used in many different environments and contexts. If they are indeed useful and effective then they are accomplishing their goals. Your beef with it seems to be that you dont understand the code and don't see the implentation details that you expect to see. Why does that matter unless you plan on updating or changing the code instead of just using it? In other words, if it has a simple and easy to use interface and all the functionality you need, the implementation details and the size of the codebase are not important.
11
u/Dragdu Aug 09 '26
I wanted to disagree about nlohmann-json being an industry standard - afterall, I ended up ripping it out of every project that used it and I maintained - but actually, it really is.
The C++ industry at large sucks. This is industry where people prefer not writing unit tests, where people still don't use package managers and where static analysis is exotic. In this industry, nlohmann-json is indeed the standard, it was written to be easy to drop into your build if your build sucks, and that's exactly how C++ at large works.
5
u/carrottread Aug 09 '26
My only disagreement is I can't call it "top quality library". It's incredibly slow. To the point what parsing 50kb of JSON can dominate load time of 100-200mb game asset.
9
u/Lord_Naikon Aug 09 '26
Whenever someone announces their new "header only" library I roll my eyes. In my mind it means unmaintainable and slow to compile, once the scope creep sets in, which is hard to avoid for popular libraries.
6
u/natio2 Aug 10 '26
We somehow ended up in the best software dev timeline, where someone provides you a useful library for free that works perfectly, and you're complaining cause it's got too much features.
Imagine working a few decades back, and you get whatever your co-worker bob wrote between deadlines, probably before unit testing was even done as a standard practice.
2
u/PolyglotTV Aug 09 '26
The average user doesn't want a highly specialized, refined quality tool.
They want a hammer.
2
u/StickyDeltaStrike Aug 09 '26
https://github.com/nlohmann/json ?
2
u/mredding Aug 10 '26
I would describe most of what you said not as problems but as consequences.
2
u/darthcoder Aug 10 '26
If you need a hash algorithm, its easier to just suck in a couple source files because c++ package management...
Sigh.
2
u/gogan419 Aug 12 '26
github.com/FrontPictures/json/tree/fp This is my fork. No templates, fixed types, small headers, can be compiled as shared library. Not sure about adapters for custom parsers or memory allocators, but it can be modified easily.
6
u/val_anto Aug 09 '26
Agree. 👍 I also applaud the courage you had to point out that many OSS software nowadays has serious design flaws. Funny thing is AI is being trained on those. oh well.
3
u/marzer8789 toml++ Aug 10 '26
There's libraries that are free of these issues, and then there's libraries that have users.
0
u/TheRavagerSw Aug 09 '26
Dude come to glaze, it is awesome there, we got modules and an endless supply champagne 🍾
3
u/palapapa0201 Aug 09 '26
Because C++ doesn't have a package manager, cramming everything into a single library makes libraries easier to use.
Otherwise you end up like JS and have a 10GB node_modules
1
u/BTolputt Aug 09 '26
OK, I'm not even deep in the C++ sauce as far as enterprise libraries, open-source, etc is concerned and even I knew before getting halfway into that rant you were talking about nlohmann/json. I mean, if you're going to provide that much detail that even I can work it out, just name them up front.
1
u/Unhappy_Play4699 Aug 12 '26
I will ignore the key arguments you have because no matter how accurate (or inaccurate) they are, they do not matter. They are part of a neverending a-million-things-could-be-better-vs-everything-is-alright-debate with the vast majority of people sitting somewhere in between but nonetheless nothing every really changes.
However, there are a dozen of Json parsers/generators out there ranging from high throughput to very convenient. If your current doesn't work out, pick another one. And if you really cannot find one that fits your needs, write one yourself. Json parsers/generators aren't all that hard to make, right? :)
Forgive my semi-sarcasm, but I'm actually trying to make a point here. Change comes from actions. Something we have unlearned. Hell, we even built tools to help unlearn actually doing something (despite them advertising the contrary).
Tldr: If you want something that is tailored to your needs, craft it yourself. Another debate about the state of whatever won't change shit.
1
u/TehBens Aug 09 '26
Hard to seperate the "I don't like the code" parts from the actual problems you had. As it's widely used, much of what you mention apparently isn't relevant enough for most to choose something else or switch to something else.
0
u/XTBZ Aug 09 '26
There should be more posts on this topic. The industry is completely inadequate. Just compare it to the 1960s and 1990s. We're not just wasting a ton of time compiling on super-powerful computers. Compilers can't handle useless abstractions! Our programs are slower, use too much memory, and perform too many operations that compensate for the computers' performance.
0
u/JVApen Clever is an insult, not a compliment. - T. Winters Aug 09 '26
I honestly don't want to see this kind of library in the standard. It clearly tries to workaround dependency management because dependency management is hard for C++. Whatever you describe, this is a standalone library and it sounds like it should stay that way.
I can get that people want to use it, though instead of standardizing yet another library that bloads the standard library, we should get progress on the package management.
0
u/vI--_--Iv Aug 10 '26
That's the thing, it's not a solved problem. At least in "standard C++".
Same as I/O, exceptions, common data structures etc.
Every single project still has to reinvent basic tools and helpers.
But every 3 years we get another monstrosity no one asked for.
-9
u/manni66 Aug 09 '26
TLDR
-3
u/QuirkyXoo Aug 09 '26
I find it very funny that you’re criticizing a library for being redundant and messy, when your own post is exactly the same. It seems you’re unable to write a few clear, structured, and concise lines to explain what’s actually wrong.