doc: Explain how to pass in non-fundamental types into functions #15922

1. 
   MarcoFalke commented at 5:11 pm on April 29, 2019: member

   There is a common misconception in C++ that one ampersand is better than no ampersand and two ampersands are better than one.
2. 
   MarcoFalke commented at 5:12 pm on April 29, 2019: member

   The text is stolen from @ryanofsky without attribution (https://github.com/bitcoin/bitcoin/pull/15849#pullrequestreview-231748721)
3. fanquake added the label Docs on Apr 29, 2019
4. in doc/developer-notes.md:512 in fae2ccda7f outdated

   507+    `const T&`.
   508+
   509+  - If a function wants to give callers the option of moving from an argument
   510+    but still allow copies, it should take plain `T`.
   511+
   512+  - If a function wants to force callers to move it should take `T &&`.
   

   ---

   ---

   

   andcoisqu commented at 5:17 pm on April 29, 2019:

   0  - If a function wants to force callers to move an argument, it should take `T &&`.
   

5. 
   sipa commented at 5:35 pm on April 29, 2019: member

   This advice is really only valid for cheaply-movable types. If moving involves copying a large portion of the data involved, you should always use a reference type (lvalue or rvalue as appropriate).
6. 
   jamesob commented at 5:51 pm on April 29, 2019: member

   Concept ACK, but I think @sipa’s comment should be incorporated.
7. 
   Empact commented at 6:45 am on April 30, 2019: member

   Maybe also mention out var references?
8. 
   practicalswift commented at 9:56 am on April 30, 2019: contributor

   Concept ACK on updating the developer notes.

   Perhaps we could re-use the relevant recommendation from the C++ Core Guidelines (edited by our C++ friends Bjarne Stroustrup and Herb Sutter) including the nice table:

   F.15: Prefer simple and conventional ways of passing information

   Using “unusual and clever” techniques causes surprises, slows understanding by other programmers, and encourages bugs. If you really feel the need for an optimization beyond the common techniques, measure to ensure that it really is an improvement, and document/comment because the improvement may not be portable.

   Normal parameter passing:

   

   Advanced parameter passing:

   

   Use the advanced techniques only after demonstrating need, and document that need in a comment.

   If we want to use the text and/or the table the C++ Core Guidelines says the following:

   We make this project available to “friendly users” to use, copy, modify, and derive from, hoping for constructive input.

9. 
   laanwj commented at 10:53 am on May 1, 2019: member

   concept ACK, as this addresses a common misconception

   as for the developer notes, in general, please do focus on things that can cause bugs and absurdly slow behavior, it’s not necessary to replicate C++ optimization guides and such, we don’t want to turn it into a 200-page document that no one can keep track of

10. MarcoFalke force-pushed on May 1, 2019
11. 
    MarcoFalke commented at 12:54 pm on May 1, 2019: member

    Added a link to https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-conventional
12. 
    practicalswift commented at 7:57 pm on May 1, 2019: contributor

    @MarcoFalke Please note that the linked Google style guide contains recommendations regarding parameter passing that are not in line with how we want things to be done:

    Output Parameters … Parameters: Input parameters are usually values or const references, while output and input/output parameters will be pointers to non-const. … Reference Arguments … void Foo(const string &in, string *out); … In fact it is a very strong convention in Google code that input arguments are values or const references while output arguments are pointers.

    I vote for not introducing a link to to the Google corporate style guide :-)

13. doc: Explain how to pass in non-fundamental types into functions faede747b3
14. MarcoFalke force-pushed on May 1, 2019
15. 
    practicalswift commented at 8:10 pm on May 1, 2019: contributor

    ACK faede747b3493544f25d601b8e02c833e54c8751
16. 
    jonasschnelli commented at 8:47 am on May 2, 2019: contributor

    ACK faede747b3493544f25d601b8e02c833e54c8751
17. MarcoFalke merged this on May 17, 2019
18. MarcoFalke closed this on May 17, 2019

    ---

19. MarcoFalke deleted the branch on May 17, 2019
20. MarcoFalke referenced this in commit 277abed604 on May 17, 2019
21. sidhujag referenced this in commit e958bc1c4c on May 18, 2019
22. PastaPastaPasta referenced this in commit 9477f60fb3 on Jun 27, 2021
23. PastaPastaPasta referenced this in commit 1027f8e954 on Jun 28, 2021
24. PastaPastaPasta referenced this in commit c306b0b315 on Jun 29, 2021
25. PastaPastaPasta referenced this in commit 39d7a8f4ea on Jul 1, 2021
26. PastaPastaPasta referenced this in commit 4f98e59c26 on Jul 1, 2021
27. PastaPastaPasta referenced this in commit 6a89afcd73 on Sep 11, 2021
28. PastaPastaPasta referenced this in commit c3fe7f7473 on Sep 11, 2021
29. PastaPastaPasta referenced this in commit 1c7188fab1 on Sep 12, 2021
30. DrahtBot locked this on Dec 16, 2021

Contributors
MarcoFalke andcoisqu sipa jamesob Empact practicalswift laanwj jonasschnelli

Labels
Docs