This living document will list my own personal frustrations when it comes to C++ software development. This is purely my own opinion, and if I am wrong or simply don't understand, feel free to provide guidance and I will update this document as I see fit. Most of my frustrations so far have been due to my lack of understanding, usually caused by improper documentation of the library I was using.
There is no good C++ YAML parser library that works out of the box and has appropriate documentation and example. I have used YAML in many programming languages, but could never get it to work reliably in C++. All I want is to read configuration files.
I have tried yaml-cpp but it breaks critical programming contracts regarding constness.
I have tried rapidyml but it has no release cycle, the tutorial does not compile, and documentation is very lacking.
Most of these projects seem to be active, yet have many open issues that don't get much attention from the maintainers, if any at all.
Just look at JSON C++ libraries, see how good they are, how complete they are, how documented they are. Why can't we have that for YAML?
https://github.com/jbeder/yaml-cpp
- Programming contract broken
- Tutorial is incomplete, does not cover trivial case of using YAML to read software configuration
https://github.com/biojppm/rapidyaml
- No release plan
- Tutorial won't compile, was not updated with latest code changes
https://github.com/jimmiebergmann/mini-yaml
- Seems to have too few users for use in a professional project
- Has issues with available PR not resolved for over a year
I switched to using JSON instead of YAML to read my configuration files. The C++ library support is much much better.
https://github.com/nlohmann/json
2020-08-29: I tried using Conan, the C++ package manager. Installation was quick and easy using pip. Then I followed the tutorial, I managed to be able to search for the package in the example. I then proceeded to search for Boost, but could not establish a connection to their package manager server. Actually, the conan command would simply stall there, not doing anything. Using strace, I was able to find out the connection had failed but the application did not seem to detect the error. Hopefully the problem is only temporary, but I cannot have this kind of disruption if I want to use that in a professional environment.
Update 2020-08-29: It takes 3 minutes to get the results. There's probably something somewhere that's waiting on a timeout. It could simply be a bug in the latest version.
Update 2020-08-29: Turns out it's a known issue. You cannot really search through the command line, but the web inteface works. Not quite sure why they don't use the same API for both.
After deciding to switch from YAML to JSON for my configuration files, I needed a good C++ library. I went with https://github.com/nlohmann/json
Their documentation is not too bad. It's all in the README.md file though, and it's quite something to go through it. It's hard to read efficiently since it's one big file. There does not seem to be any API documentation other than through Doxygen, and you have to build it yourself.
There is no mention of error handling in the tutorial. It is probably the most important part of any project and there is no mention on how to handle errors. Do I test the value as a boolean? Do I call a specific function to make sure it parsed the file correctly? Do I catch an exception and if so, which one?
Turns out it throws exceptions when it doesn't like something. For example, if it fails to parse the file, it will throw a nlohmann::detail::parse_error, which is mentioned nowhere in the documentation. Good thing I tested for it, otherwise this would have been yet another bug that crashes our program.
Reading through the code, it seems there's an exceptions.hpp file. The exceptions inherit a base class of nlohmann::detail::exception, which in turn inherits std::exception. This is bad design as per the C++ Core Guidelines E.14: https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines.html#Re-exception-types.