isocpp / isocpp/CppCoreGuidelines
F.18: Example should provide more details about caller and owning type
@hsutter is already working on this.
Since Apr 16, 2018.
- Dominant language
- CSS
- Stars
- 45.3k
- Forks
- 5.6k
- PR merge metrics
- No merged PRs in 30d
Description
This was an issue I hit yesterday. For someone like me who is just becoming aware of some of the modern C++ standards but doesn't yet understand all the details, the example left me more confused.
In particular, I think this section pretty much requires an understanding of rvalue references. A link to a resource like this one (or another part of the guide, perhaps) would be a great start. Currently, the only outbound link is here, and the link leads "That could be dangerous," which to me signifies some advanced topic that is not worth following until I have a better understanding. (Indeed, the move semantics section doesn't really make sense if you don't know what std::move actually does).
To help improve it, I think these could be further clarified clarified:
- "call site" can refer to the call of the function taking the parameter or the call of the ownership operation. My first instinct would be to assume it is the former, but the example below only shows the latter, which includes the std::move call. Expanding the example to include the caller would help.
- "use p ... possibly std::move(p) onward somewhere else" - this is frustrating as it doesn't actually describe how to do the move operation and what the owning type is. Expanding the example to include that would help.
- Section I.11 and Section R.30 seem to have different guidance, but none are linked. Included a related section - particularly when discussing smart pointers in the Exception - would allow readers to easily find the correct guidance.
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.