Contributor Checklist

Before submitting a library for review, work through this checklist to help polish the library to a high standard.

Code Quality and Design

Examining your code, can you verify:

  • Consistent Coding Style - naming conventions, indentation, spacing. Consider using clang-format for consistency.

  • Modular Design - the code should be broken down into small, manageable, and reusable components, and fit into the structure of the Boost Super-Project.

  • Avoid Code Smells - eliminate dead code, redundant logic, overly complex functions, and other common red-flag issues.

  • Adherence to C++ Standards - ensure the library is compatible with a current standard (for example, C++17 or later).

  • Template Usage - are templates appropriately used, and consider the potential impact on compile times.

  • Exception Safety - make sure the library has well-defined behavior when exceptions are thrown. Aim for strong or basic exception safety guarantees.

  • Thread Safety - if relevant, ensure thread safety or clearly document any multi-threading limitations.

  • Minimize Dependencies - use other Boost components when appropriate - ideally the latest incarnation, and avoid unnecessary external and circular dependencies.

Refer to Design Best Practices for considerably more detail.

Documentation

Documentation should be on a website (rather than, say, a downloadable pdf file) so that it can be regularly and easily be updated. It should also be a single document as many reviewers will not explore beyond one link.

  • The Introduction or Overview should compel an interested developer to read further. The purpose of the library - in not-too-technical terms - should be clear as daylight. What kind of task this library is the solution for should be well understood by reading the introduction completely, but no further. Remember that it is not experts, but developers struggling, who most often turn to documentation for help.

  • Have a developer unfamiliar with the library read the introduction. If they struggle to understand it, revise accordingly.

  • Include a sub-section on testimonials, if you have any that are noteworthy.

  • Include information on how long the library has been stable, especially if it has been used for a significant period before the submission to Boost.

Divide the rest of the documentation into three sections:

1. Comprehensive User Guide

  • how to install the library - mentioning B2 and CMake as appropriate

  • the dependencies

  • the requirements - compilers, operating systems, hardware, etc.

  • a "hello world" example

  • architecture and rationale - include historical information and timelines if they impacted the design.

  • license

  • references

  • acknowledgements

Examples and Tutorials

  • how to get started

  • common use cases

  • advanced use cases

  • corner cases

  • common patterns - for example, how to handle common errors

2. Complete Reference Documentation

Provide detailed descriptions of all:

  • classes

  • interfaces

  • functions

  • properties

  • macros

  • types

  • constants

  • error codes - ensure that error messages are clear and helpful for debugging

  • exceptions

It can be helpful to use tools like Doxygen or QuickBook.

3. Guidelines for Contribution

Make it easy for others to understand the codebase and, in the course of time, enable them to contribute their own issues, proposals and code.

  • Provide links to the library source where appropriate

Testing

Ensure comprehensive test coverage for all functionalities.

  • Unit Tests - use Boost.Test or another test framework.

  • Edge Cases and Boundary Conditions - especially for algorithms and data structures.

  • Cross-Platform Compatibility - verify that the library works on different platforms (Windows, Linux, macOS). Consider using CI tools like GitHub Actions or Travis CI to automate this process.

  • Build Configurations - test with different compilers (GCC, Clang, MSVC) and optimization levels.

  • Stress Tests - add stress tests (low memory, high CPU usage, etc.) to see how the library performs under heavy loads.

Efficiency and Performance

As a minimum for validating your library performance, consider:

  • Including benchmarks to demonstrate the library’s performance. Compare against existing solutions if possible.

  • Optimizing for memory usage and consider using std::move and std::unique_ptr where appropriate to minimize allocations.

  • Avoiding unnecessary copies by using const &, std::move, and std::forward properly to avoid unnecessary data copying.

Boost-Specific Requirements

Boost library technical requirements are laid out in detail:

Usability and API Design

For usability, verify that you have:

  • A Simple and Intuitive Interface - avoid unnecessarily complex APIs.

  • A Consistent API - consistent naming conventions, argument orders, and return types across the library.

  • Clear Error Handling - clearly define and handle error cases. Use exceptions where appropriate and document expected exceptions.

  • Template Type Deduction - ensure templates are designed to support type deduction and intuitive usage.

Pre-Review Feedback

Before submitting for a formal review, have you:

  • Sought feedback from a smaller group of developers. Consider hosting the code on GitHub to get initial feedback from your community.

  • Addressed all feedback from the pre-submission review.

Examples of Successful Libraries

Consider a brief study of some existing popular Boost libraries and use them as benchmarks for quality and completeness. Recommended libraries for study include:

See Also

Edit this Page