[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:
Duplicate
is duplicated by SERVER-42168 assert_util.h needs documentation Closed
is duplicated by SERVER-51484 exception_architecture.md refers to t... Closed
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.
We could provide a link to that wiki page at a minimum and maybe that would help.

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 ]

https://mongodbcr.appspot.com/474270091

Generated at Thu Feb 08 04:59:46 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.