Document How to Use the Data Type [DI7] [HOW]
Tip DI7
Make sure how a data type is intended/best used is clear. If a programmer can’t figure out how to use a data type - or use it correctly - just be examining its interface (without diving into implementation details), they’re not set up for success. They may get frustrated and give up. If they don’t give up, they may not figure out how to properly use the data type or have to waste a ton of time reverse engineering your code.
Hopefully, much of this can come from well-designed function interfaces that make it obvious how a data type like a class should be used, and sometimes such details are best relegated to individual function documentation (rather than at a class level). Regardless of where the documentation sits, documenting usage assumptions, best practices, and limitations can all be important things to document.
The following examples demonstrate some cases where data type-level usage documentation was important to add onto previous documentation:
