isocpp / isocpp/CppCoreGuidelines
I.6, I.7 balance & improve introductions to these 2 rules
Open
@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:
- 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
}
- 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;
}
- 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.
- In I.7, move first explanatory sentence ("Here, we (incautiously)...") after Example, bad to I.6, since this sentence discusses preconditions, not postconditions.
- 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(...
- 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. - In general regarding these two rules, we know Contracts are on the horizon, but existing guidance on
Expects()andEnsures()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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.