isocpp / isocpp/CppCoreGuidelines

I.6, I.7 balance & improve introductions to these 2 rules

Open
#1,384 3 comments 0 reactions 1 assignee View on GitHub

@GabrielDosReis is already working on this.

Since Mar 21, 2019.

Dominant language
CSS
Stars
45.3k
Forks
5.6k
PR merge metrics
No merged PRs in 30d

Description

Suggest:

  1. Improve I.6 Example with a reference to I.7 as follows:
int area(int height, int width)
{
    Expects(height > 0 && width > 0);            // good
    if (height <= 0 || width <= 0) my_error();   // obscure
    // ...
    // see I.7 for postcondition guidance
}
  1. Improve I.7's first Example, bad's "Consider using" code with a reference to I.6 as follows:
int area(int height, int width)
{
    // see I.6 for precondition guidance
    auto res = height * width;
    Ensures(res > 0);
    return res;
}
  1. Copy I.7's introductory Example, bad to I.6, since it's relevant in both. This would allow each rule to stand better on its own.
  2. In I.7, move first explanatory sentence ("Here, we (incautiously)...") after Example, bad to I.6, since this sentence discusses preconditions, not postconditions.
  3. In I.7 (and similarly in I.6, after implementing above suggestions), suggest rewording so that the improvement to the first Example, bad appears in a new Example, better, like this:

... Overflow can happen.

Example, better Consider using:

int area(...

  1. In I.7's suggested improvement on the first example, Ensures(res > 0); is a check for addition overflow given 2 positive addends. It is not a check for multiplication overflow (see http://www.cplusplus.com/articles/DE18T05o/). This might have the unintended consequence of reducing the reader's confidence in the validity of this rule as a whole.
  2. In general regarding these two rules, we know Contracts are on the horizon, but existing guidance on Expects() and Ensures() is very sparse via a simple Google search today. These rules are the best place to clearly guide C++ developers in the recommended direction while we all await Contracts.

I believe suggestions in this issue would also bring improvement (but not closure) to issue #49, which also discusses I.7.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.