Documentation - or the Art of Preparing for the Unknown

By Peter Turcan on

Jan 10, 2025

The C++ Alliance supports both the great Boost Libraries and a current proposal for a memory/type/thread-safe version of C++ called Safe C++. They are not connected in any way other than the Alliance’s support. However, looking ahead, it seems smart for at least contributors to Boost to be aware of the progress and terminology of the Safe proposal. Before a contributor could do much the Safe C++ proposal would both have to be accepted and then implemented (super-easy to say and mountain of work to do). Purely for education purposes I added terms used in the Safe C++ discussions to the User Guide Glossary. Even as a developer or programmer-writer for 40 years, I had no idea what the term “borrow checking” meant. And if I have no clue, I assume others don’t know either - so in it goes to the glossary - and a dozen or more other terms too. Also, a few questions and answers - a reality check on the proposal - added to the Contributor Guide FAQ.

I remember the days when the precursor to C++ came out, C, and was both super impressed by its low-level power and unconvinced about the lack of bounds checking. When would it ever make sense to write a 40 character string to a 20 character buffer and not get an error? Maybe I thought some super-clever developer might be able to use this for some task and save a few micro-seconds in the process. As an aficionado of logic, this is not a feature of any interest to me. The reality is this absence of checks has become a security black hole - not something I saw coming. Safe C++ at the very least seems like a worthwhile investigation into the possibilities.

Another reality check - our Formal Review process. On the one hand there is the best-of-intentions, on the other programming reality - “too much consensus can lead to poor design” - another way of saying “a camel is a horse designed by a committee”. Or “avoid teaser comments” - where devs might feel you are onto something but not sure what! I added these, and other, pieces of tribal knowledge - originating from Peter Dimov - to our Formal Reviews Guide.

And while on the subject of Formal Reviews, I added a reviewers checklist and a short section on “Rejecting a Library”, with links to examples of appropriate wording used in the past.

Some documentation is written for a wide audience (the Introduction to Boost, for example), and some for a tiny audience (the Organization Guide appendix) which is really only for those few helping build and maintain the Boost library repo.

With some help and research, I added a section on Building with CMake - seems like a powerful tool for creating customized builds of stuff - including Boost libraries. Mostly I have been a fan of tools that do this for you - such as Visual Studio - but I do understand many devs don’t like the opaqueness of IDE tools - they want to see and control what is going on.

Outside of the Boost guides, I reviewed the documentation for proposed libraries, including the new Hash2. Great to see new libraries joining Boost, and my goal of reviewing the docs is really to lower the bar to entry - so the less-skilled, less-experienced or just less-confident feel more comfortable joining this community!