Peter Turcan Q3 2024 - From Murky to Clear - Shedding Light on the Foggy Bits – User Guide and Contributor Guide Status Update

By Peter Turcan on

Oct 25, 2024

• Authored and published a new topic on Debug Visualizers in the Contributor Guide. Debug Visualizers offer a powerful way to simplify the debugging process by allowing developers to see complex data structures in a more understandable format. The two main sections are Debug Visualizers in MSVC (Microsoft’s built in visualizers for Visual Studio) - utilizing the Natvis display language, and Debug Visualizers in GDB (the visualizers for the GNU Debugger) - utilizing Python templates to create pretty-printers. To quote the article “Debug Visualizers are particularly useful in scenarios where data structures are complex and difficult to interpret from raw memory views.” The article includes sample code for visualizing simpler libraries like boost::optional, and more challenging scenarios from boost::asio. Whether you’re new to debugging or an experienced developer, taking the time to master these tools will pay off big-time in the long run!

• At the other end of the technical spectrum from Debug Visualizers, I added a User Guide Glossary, with 140 terms, mostly acronyms found in our Slack channel conversations. This task came from a user who became befuddled over some of the terms we use freely in our Slack conversations, but are not always widely understood. These acronyms vary from the conversational “AFAIK” (as far as I know) through to technical shorthand, such as “XSS” (cross-side scripting, a security vulnerability), through to some of the esoteric Boost terms, such as “uBlas” for Basic Linear Algebra.

• FAQs are often frequently visited web pages, and I added a section on the Standard Library to the User Guide FAQ. There is often some confusion over whether to use a Boost or Standard library. This FAQ section does not put this to rest indefinitely, as both library collections evolve, but should help describe the issues and what to consider when deciding between a Standard or Boost library.

• On a similar vein, updated various other sections of the User Guide FAQ, and Contributor Guide FAQ, as questions and answers become available following Slack or email conversations on the various Boost channels and forums.

• As the size of the User Guide and Contributor Guide grow, navigation also grows in importance - especially with long topics. Adding better linking and table of contents and See Also sections helps improve the user experience.

• As C++ faces some challenges due to its lack of memory safety, such as the language RUST, it was educational for me to read and provide feedback on a Safe C++ paper due to be presented at a conference. Safe C++ is a complex and detailed proposal to right what I see as a historical wrong (though other developers might describe it as “freedom”) and address the memory, type, and exception safety issues that have inadvertently enabled security threats.