Uploaded image for project: 'Core Server'
  1. Core Server
  2. SERVER-42169

assert_util.h needs documentation

    XMLWordPrintable

    Details

    • Sprint:
      Dev Tools 2019-09-09, Dev Tools 2019-09-09, Dev Tools 2019-09-23, Dev Tools 2019-11-04

      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.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              backlog-server-servicearch Backlog - Service Architecture
              Reporter:
              billy.donahue Billy Donahue
              Participants:
              Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

                Dates

                Created:
                Updated: