Documentation and Samples - undefined behavior isn’t a bug — it’s a lifestyle

By Peter Turcan on

Apr 8, 2025

My focus this quarter has been on drawing in C++ developers who are new to the Boost libraries. When I did my time at Microsoft, writing API documentation, THE most common question from the developer community was for sample code - more samples - better samples - samples with error handling - samples that are best practices. The easiest explanation of what is going on is so often a commented and runnable piece of sample code.

To this end, I created - with help from AI - sample code for all of the “Common” and “Advanced” scenarios in the User Guide. This did help me a lot too, in understanding, for example, how a parser is put together in Boost.Spirit, peer-to-peer chat using Boost.Asio, how processes message each other using Boost.Thread, what “clustering” means in machine learning and how the Boost Numeric and Random libraries help build algorithms to make sense of it all.

This work also helped me understand how much I can sometimes offload tedious stuff onto a Boost library - from simple date and time formats, localized strings, and the like, to meatier issues like thread-pools and message-queues - all stuff I can see as super-helpful to so many developers building new apps and tools and libraries and front-ends and back-ends and anything else.

I did add one section to the “Common Scenarios” list: Finance. Seemed like this topic should go straight into security, cryptography in this case, and the sample I chose was for a simple wallet with Ed25519 signing (a public-key signature algorithm). If you love Ph.D level math, then cryptography might just be the right field for you - yikes cryptography is mathematically dense!

In addition to the chunks of runnable sample code, I added a section on Dependencies - and how to tame the “dependency hell” beast - a section on Macros - we have many, some might say too many, macros available and it seemed pertinent to point out the most useful. And a section on Code Comments - generally the best current practices - I am a fan of code comments - particularly for my own use - so often means you don’t have to commit awkward stuff to memory.

As always small updates are part of the mix - updates to Boost history, managing reviews, introduction to the libraries - always feels right to keep documentation fresh.