doc: various developer notes updates #25092

1. 
   jonatack commented at 2:25 pm on May 9, 2022: member

   A few updates noticed while working on a lifetimebound section.

   • Remove obsolete BDB ENABLE_WALLET section (only one file, src/wallet/bdb.h, still has a db_cxx.h BDB header)
   • Prefer Python for scripts in developer notes (and a few miscellaneous touch-ups)
   • In the code style section, add a link to the internal interface exception so that people are aware of it
   • Add a “C++ functions and methods” section
   • Add a Clang lifetimebound attribute section
2. Remove obsolete BDB ENABLE_WALLET section in developer notes 370120ec2f
3. Prefer Python for scripts in developer notes

   along with a few miscellaneous touch-ups.

   fc4cb857cc
4. Link in developer notes style to internal interface exception 5fca70f5b1
5. laanwj added the label Docs on May 9, 2022
6. in doc/developer-notes.md:1395 in 5fca70f5b1 outdated

   1390@@ -1390,7 +1391,7 @@ communication:
   1391   ```
   1392 
   1393 - For consistency and friendliness to code generation tools, interface method
   1394-  input and inout parameters should be ordered first and output parameters
   1395+  input and in-out parameters should be ordered first and output parameters
   1396   should come last.
   

   ---

   ---

   

   laanwj commented at 2:39 pm on May 9, 2022:

   Maybe we can add something that we prefer returning values directly to “output parameters”. This was written before the days of std::optional etc.

   ---

   

   jonatack commented at 3:41 pm on May 9, 2022:

   Good idea, done in 91d6d4a2337719cce48532dd614bb3.
7. 
   laanwj commented at 2:39 pm on May 9, 2022: member

   Looks good to me.
8. jonatack force-pushed on May 9, 2022
9. w0xlt approved
10. 
    w0xlt commented at 6:45 pm on May 9, 2022: contributor

    ACK https://github.com/bitcoin/bitcoin/pull/25092/commits/91d6d4a2337719cce48532dd614bb345be66fbbf
11. in doc/developer-notes.md:148 in 91d6d4a233 outdated

    140@@ -138,6 +141,16 @@ public:
    141 } // namespace foo
    142 ```
    143 
    144+Coding Style (C++ functions and methods)
    145+--------------------
    146+
    147+- Input and in-out parameters should be ordered first and output parameters
    148+  should come last.
    

    ---

    ---

    

    laanwj commented at 11:55 am on May 10, 2022:

    0- *Rationale*: API consistency.
    

    ---

    

    jonatack commented at 12:34 pm on May 10, 2022:

    Added (thanks!)
12. in doc/developer-notes.md:151 in 91d6d4a233 outdated

    146+
    147+- Input and in-out parameters should be ordered first and output parameters
    148+  should come last.
    149+
    150+- Prefer returning values directly (using `std::optional`, where helpful) to
    151+  using output parameters.
    

    ---

    ---

    

    laanwj commented at 11:58 am on May 10, 2022:

    0- *Rationale*: Less error-prone (no need for assumptions what the output is initialized to on failure). Easier to read.
    

    ---

    

    jonatack commented at 12:35 pm on May 10, 2022:

    Added (thanks!) along with some ideas from https://google.github.io/styleguide/cppguide.html#Inputs_and_Outputs.
13. jonatack force-pushed on May 10, 2022
14. in doc/developer-notes.md:153 in 8d9ca1ff1a outdated

    148+  in-out parameters, followed by any output parameters.
    149+
    150+- *Rationale*: API consistency.
    151+
    152+- Prefer returning values directly to using in-out or output parameters. Use
    153+  `std::optional` where helpful for returning values (as well as for optional
    

    ---

    ---

    

    laanwj commented at 12:40 pm on May 10, 2022:

    Good point. I think using std::optional for optional inputs (instead some magic default value, if there is no real default) has enough merit to be called out separately.

    ---

    

    jonatack commented at 12:42 pm on May 10, 2022:

    has enough merit to be called out separately.

    Suggesting splitting it out to a separate bullet point?

    ---

    

    laanwj commented at 12:47 pm on May 10, 2022:

    I do think that’s clearer.

    ---

    

    jonatack commented at 1:01 pm on May 10, 2022:

    Done.
15. Add C++ functions and methods section to developer notes

    Credit for some parts to the Google C++ Style Guide "Inputs and Outputs"
    section at https://google.github.io/styleguide/cppguide.html#Inputs_and_Outputs
    
    Co-authored-by: laanwj <126646+laanwj@users.noreply.github.com>

    e66b321fd1
16. jonatack force-pushed on May 10, 2022
17. Add clang lifetimebound section to developer notes 654284209f
18. 
    laanwj commented at 2:43 pm on May 10, 2022: member

    ACK 654284209f30fd309c326a527cda1d2d7385cee8
19. 
    DrahtBot commented at 8:06 pm on May 10, 2022: member

    The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

    Conflicts

    Reviewers, this pull request conflicts with the following ones:

    • #24846 (developer-notes: allow lowerCamelCase for methods by jamesob)

    If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

20. 
    jarolrod commented at 7:30 am on May 16, 2022: member

    code review ACK https://github.com/bitcoin/bitcoin/commit/654284209f30fd309c326a527cda1d2d7385cee8

    Nice improvements to the dev docs 👍

21. MarcoFalke merged this on May 16, 2022
22. MarcoFalke closed this on May 16, 2022

    ---

23. jonatack deleted the branch on May 16, 2022
24. sidhujag referenced this in commit ee5e94b5de on May 28, 2022
25. DrahtBot locked this on May 16, 2023

Contributors
jonatack laanwj w0xlt DrahtBot jarolrod

Labels
Docs