[SERVER-42169] assert_util.h needs documentation Created: 11/Jul/19 Updated: 05/Jan/23 |
|
| Status: | Backlog |
| Project: | Core Server |
| Component/s: | Internal Code |
| Affects Version/s: | 4.3 Desired |
| Fix Version/s: | None |
| Type: | Improvement | Priority: | Major - P3 |
| Reporter: | Billy Donahue | Assignee: | Backlog - Service Architecture |
| Resolution: | Unresolved | Votes: | 0 |
| Labels: | new-eng, sa-remove-fv-backlog-22 | ||
| Remaining Estimate: | Not Specified | ||
| Time Spent: | Not Specified | ||
| Original Estimate: | Not Specified | ||
| Issue Links: |
|
||||||||||||
| Assigned Teams: |
Service Arch
|
||||||||||||
| Sprint: | Dev Tools 2019-09-09, Dev Tools 2019-09-09, Dev Tools 2019-09-23, Dev Tools 2019-11-04 | ||||||||||||
| Participants: | |||||||||||||
| Description |
|
The wiki describes how to choose among our asserts. Engineers chronically choose the wrong assertion style. The header itself has no documentation. https://wiki.corp.mongodb.com/display/HGTC/MongoDB+Assertions+and+You One problem with this is that the wiki is not accessible outside the company.
The much better and more complete solution is to write inline header docs in assert_util.h (and invariant.h), where the implementation can perhaps answer questions that the documentation may not address or may leave ambiguous. The inline docs will appear in IDE hovertext and be source-controlled and versionable.
We should also now be linking to the docs/exception_architecture.md document, which has a little more about the behavior of the different [[:alpha:]]assert facilities. |
| Comments |
| Comment by Billy Donahue [ 11/Jul/19 ] |