<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

<style type="text/css">
pre {margin-left:20pt; font-family: "OCR A Extended", "Consolas", "Lucida Console", monospace; }
code {font-family: "OCR A Extended", "Consolas", "Lucida Console", monospace; }
pre > i   { font-family: "OCR A Extended", "Consolas", "Lucida Console", monospace;  font-style:italic; }
code > i  { font-family: "OCR A Extended", "Consolas", "Lucida Console", monospace;  font-style:italic; }
pre > em  { font-family: "OCR A Extended", "Consolas", "Lucida Console", monospace;  font-style:italic; }
code > em { font-family: "OCR A Extended", "Consolas", "Lucida Console", monospace;  font-style:italic; }
body { color: #000000; background-color: #FFFFFF; }
del { text-decoration: line-through; color: #8B0040; }
ins { text-decoration: underline; color: #005100; }

p.example   { margin-left: 2em; }
pre.example { margin-left: 2em; }
div.example { margin-left: 2em; }

code.extract { background-color: #F5F6A2; }
pre.extract  { margin-left: 2em; background-color: #F5F6A2;  border: 1px solid #E1E28E; }

p.function    { }
.attribute    { margin-left: 2em; }
.attribute dt { float: left; font-style: italic;  padding-right: 1ex; }
.attribute dd { margin-left: 0em; }

blockquote.std    { color: #000000; background-color: #F1F1F1;  border: 1px solid #D1D1D1;  padding-left: 0.5em; padding-right: 0.5em; }
blockquote.stddel { text-decoration: line-through;  color: #000000; background-color: #FFEBFF;  border: 1px solid #ECD7EC;  padding-left: 0.5empadding-right: 0.5em; ; }
blockquote.stdins { text-decoration: underline;  color: #000000; background-color: #C8FFC8;  border: 1px solid #B3EBB3; padding: 0.5em; }
table.header { border: 0px; border-spacing: 0;  margin-left: 0px; font-style: normal; }
table { border: 1px solid black; border-spacing: 0px;  margin-left: auto; margin-right: auto; }
th { text-align: left; vertical-align: top;  padding-left: 0.4em; border: none;  padding-right: 0.4em; border: none; }
td { text-align: left; vertical-align: top;  padding-left: 0.4em; border: none;  padding-right: 0.4em; border: none; }
</style>

<title>P2038R0 &mdash; Proposed nomenclature for contract-related proposals</title>

</head>
<body>

<table class="header"><tbody>
  <tr>
    <th>Document number:&nbsp;&nbsp;</th><th> </th><td>P2038r0</td>
  </tr>
  <tr>
    <th>Date:&nbsp;&nbsp;</th><th> </th><td>2020-01-11</td>
  </tr>
  <tr>
    <th>Audience:&nbsp;&nbsp;</th><th> </th><td>SG21</td>
  </tr>
  <tr>
    <th>Reply-to:&nbsp;&nbsp;</th><th> </th><td><address>Andrzej Krzemie&#324;ski &lt;akrzemi1 at gmail dot com&gt;</address>
                                                <address>Ryan McDougall &lt;mcdougall dot ryan at gmail dot com&gt;</address></td>
  </tr>
</tbody></table>

<h1>Proposed nomenclature for contract-related proposals</h1>

<p>This document proposes a number of terms that we recomend to authors of contract-related proposals, and SG21 members for use, in order to avoid misunderstandings.
   The terms have been chosen so that:</p>

<ol>
<li>Names that have overloaded meaning, are ambiguous or misleading are avoided; in particular:
   <ul>
   <li>"assume" &mdash; as it is not clear who assumes: it can have meaning of
       <code>__builtin_assume()</code> or it can have meaning as in,
      "function <em>assumes</em> that its precondition holds".</li>
   <li>"expect" &mdash; as it seems only to express an emotional state;
       is not clear what is the relevance of these expectations.
       You can "expect" that people will use your function incorrectly.</li>
   <li>"assert" &mdash; as "assert" could mean "trust me, I say this and this is true",
        or "test this hypothesis for me". In fact, clang-tidy interprets <code>assert()</code> in the former way:
        if it can see expression <code>e</code> to be asserted, it does not try to verify if it is true: instead,
        it just trusts the programmer.</li>
   <li>"check" (used alone) / "contract check" &mdash; as it implies that some run-time checking will
       be performed or required, whereas some predicates are not even
       expressible as code that could be executed.</li>
   <li>"contract" (used alone) &mdash; as this is something between the humans: not something that function declarations or the
       implementation would ever be affected with.</li>
	  </ul>
	  </li>

<li>The focus is shifted from generating additional code for run-time checking by the compiler to declaring information
   consumable by other tools that the Standard refers to as "implementation", such as static analyzers or sanitzers.
   </li>

</ol>


<h2><a name="recommendations">Recommended terms</a></h2>


<h3><a name="recommendations.contract_annotation"><em>Contract annotation</em></a></h3>

<p>It has a <em>location</em> in code: e.g., just before the function execution begins, or just after the function execution end successfully.
   It has a <em>predicate</em>, such as <code>p != nullptr</code>. Its "semantics" is: if the execution reaches the location of contract anntation,
   and the predicate can be determined (not necessarily by evaluating it) to be <code>false</code>, then the program has a <em>contract violation</em>.
   The information about a contract violation in the program
   can be used in different ways by different tools, including the compiler.
   </p>

<p>Thus, contract annotation helps provide a definition of a bug that is understandable by machines.
   Becuse contract violation is for sure a manifestation of a bug.
   </p>

<p>Rationale: A longer term "contract annotation" is recommended in order to avoid shorter "contract" which can also mean "everything that function guarantees and expects,
   including runtime performance guaranties." Also, a "contract" is a pair: a precondition and a postcondition, such as "the output is 2 provided that the input is 1",
   and satement "the output is 2" alone is not a contract.
   </p>


<h3><a name="recommendations.contract_annotation"><em>Contract violation</em></a></h3>

<p>A contract violation results from an interaction between the code before the contract annotation and the contact annotation
itself. The behavior of a program with a contract violation can differ from one translation to the other based on compiler
switches. This is similar to implementation-defined behavior except that we try to specify in more detail what the variance
in behavior is, and under what conditions.</p>

<p>A program with a contract violation can still be a well-formed, UB-free program. Unless other UB kicks in later on, you can
still reason about the behavior of the program in terms of operations on the abstract machine.</p>

<p> Contract violation is a symptom of a bug located either before the contract annotation or inside its predicate.
    Contract annotations can detect symptoms of bugs, but not bugs themselves. Implementations are encouraged to detect
    and prevent contract violations by different means. Although there may be reasons for intentional contract violations
    (e.g., in unit tests), it is generaly agreed that the information about these violations from static
    anayzers is welcome, and never treated as "false positives".
    </p>

<p>Rationale: speaking in terms of "contract violation" (or the lack thereof) avoids using word "expect" as in
   "a precondition is 'expected' to hold", where it is not clear if an "expectation" has any formal meaning or
   consequences. Term "library UB" is also not encouraged as there might be no library in sight when a programmer
   puts a contract annotation in her function.</p>

<h3><a name="recommendations.fact"><em>Fact</em></a></h3>

<p> An information that an implementation has about the state of variables at the given point of program executon.
    A fact can be used for different things by the implementation, including code transformtions. E.g.,
    </p>

<pre>int normalize(int i)
{
  if (i &gt; 0) return 1;
  if (i &lt; 0) return -1;

  <em>// at this point it is a fact that `i == 0`</em>
  return i; <em>// can be replaced with `return 0;`</em>
}
</pre>

<h4><a name="recommendations.fact.derived"><em>Derived fact</em></a></h4>

<p> A fact, like the one illustrated above, that the implementation obtains by means other than direct input from the programmer.
    A fact derived from other facts is a derived fact.
    </p>


<h4><a name="recommendations.fact.ub_derived"><em>UB-derived fact</em></a></h4>


<p>A derived fact obtained through special properties of undefined behavior; e.g.,</p>

<pre>int g(int i)
{
  if (i != 0)
    *((void*)0) = 0; <em>// UB</em>

  <em>// at this point it is a (UB-derived) fact that `i == 0`</em>
  return i; <em>// can be replaced with `return 0;`</em>
}</pre>


<h4><a name="recommendations.fact.injected"><em>Injected fact</em></a></h4>

<p>An injected fact is a fact that an implementation cannot derive by other means than by direct input from the programmer
   through a dedicated instruction. </p>

<pre>int f(int i)
{
  __builtin_assume(i == 0); <em>// Compiler is allowed to apply code transformations as if `i == 0` were true.</em>

  <em>// at this point it is an (injected) fact that `i == 0`</em>
  return i; <em>// can be replaced with `return 0;`</em>
}</pre>

<p> Rationale: The usage of somewhat artificial terms "injected/derived fact" is recommended in order to avoid terms "assume" and "assert" that
    have multiple meanings in this context.</p>

<h3><a name="recommendations.fact.runtime_check"><em>Run-time check</em></a></h3>

<p>From a contract annotation in location <em>L</em> with predicate <code>P</code>, an implementation can, under implementation-defined conditions (but we try to specify the conditions with "levels", "build modes" and other "toggles"), insert at location <em>L</em> a piece of code that is executed at run-time, possibly with side effects, of the form:</p>


<pre>{
  if (!(P)) HANDLE_CONTRACT_VIOLATION();
}
</pre>

<p>This is called a <em>run-time check</em>. <code>HANDLE_CONTRACT_VIOLATION()</code> is subject to further implementation-defined behavior,
   such as calling user-provided funcion, or doing nothing, or maybe doing something even different.
   </p>

<p>This definition leaves open the question whether or not <code>P</code> should be allowed to have side effects, as well as what "side effects" would mean in this context.
   </p>

<p>When a run-time check is inserted from a contract annotation with predicate <code>P</code>, and <code>HANDLE_CONTRACT_VIOLATION()</code>
   is a call to a function that never returns normally, then <code>P</code> is a derived fact after the run-time check.
   </p>

<p>Rationale: using a compound "run-time check" as something produced from "contract annotation" makes it clear that the two are different things.
   A run-time check is only one of a number of uses of contract annotations.
   </p>


<h3><a name="recommendations.function_contract"><em>Function contract</em></a></h3>

<p> A <em>function contract</em> of function <code>f</code> is an information associated with <code>f</code>.
    This information is not necessarily consumable by automated tools or machines. This is an information meant
    for humans, either provided in the form of documentation or comments in the declaration of <code>f</code>,
    necessary to be able to correctly call and implement <code>f</code>. This is a means of communication between
    the implementer and the user of <code>f</code>.
    </p>

<p> A function contract consists of two parts indicating (1) what the function guarantees,
    and (2) under what conditions. The things that a function can guarantee include:
    </p>

    <ul>
        <li>that certain values are never returned (function's range),</li>
        <li>the relation of output values to the input values (e.g., that the result will be the sum of the input parameters),</li>
        <li>runtime complexity,</li>
        <li>how function failures are communicated,</li>
        <li>level of thread safety,</li>
        <li>level of exception safety.</li>
      </ul>

<p> The conditions that the function contract of function <code>f</code> can include:
   </p>

   <ul>
       <li>what input values are not allowed (function's domain),</li>
       <li>up to how many times can <code>f</code> be called,</li>
       <li>what functions have to be called prior to calling <code>f</code>.</li>
     </ul>

<p> While this is not a complete definition of "function contract", it reflects its relevant properties:</p>

<ol>
    <li>Function contract cannot be fully expressed in C++,
        even if we add "contract support" to the language.
        </li>

    <li> Parts of function contract can be expressed using different features of c++:
        <ul>
            <li>annotations on functions such as <code>noexcept</code> or <code>[[noreturn]]</code>,</li>
            <li>strong types, such as <code>Range&lt;int&gt;</code> instead of <code>std::pair&lt;int, int&gt;</code>, </li>
            <li>precondition and postcondition contract annotations.</li>
            </ul>
        </li>
    <li>Contract annotations can only express a subset of what function contract
        guarantees or under what conditions the guarantees are provided.
        </li>
    <li>Function contract does not describe full semantics of a function,
        and a function can be called with its contract violated and produce
        the results desired by the programmer, even if these results are not
        guaranteed in the contract. For instance, function <code>f</code>'s
        contract can say that it is a contract violation to pass a null pointer
        as an input. However, the implementer of <code>f</code> can nonetheless
        runtime-check if the input pointer is null and throw an exception
        in this case. The caller may have learned about this by means other than
        function contract: e.g., by looking at the implementation, and gained
        confidence that in this release of the library this will throw, even if
        not guaranteed in the contract.
        </li>
  </ol>

<p> Rationale: Using a longer term "function contract" makes it clear that we do not mean a single precondition/postcondition.
    </p>


<h2><a name="literature">Ackowledgements</a></h2>

<p>The distinction between the contract as a whole and individual preconditions and postconditions was taken from
   <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1332r0.txt">[P1332r0]</a>. The unambiguous terms "injected fact"
   and "derived fact" have been suggested by Herb Sutter. Joshua Berne and Hyman Rosen helped shape the definitions.
   </p>

<h2><a name="literature">References</a></h2>

<ol>
  <li>[P0542r5] -- G. Dos Reis, J. D. Garcia, J. Lakos, A. Meredith, N. Myers, B. Stroustrup, "Support for contract based programming in C++" <br>
      (<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/P0542r5.html">http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/P0542r5.html</a>).
  </li>
  <li>[P1332r0] -- Joshua Berne, Nathan Burgers, Hyman Rosen, John Lakos , "Contract Checking in C++: A (long-term) Road Map" <br>
      (<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1332r0.txt">http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1332r0.txt</a>).
  </li>

</ol>

</body>
</html>
