use EXIT_ codes instead of magic numbers for exit(…) and main return values #1609

1. 
   theStack commented at 1:23 am on September 27, 2024: contributor

   This is really only a minor issue, but I noticed while reviewing #1479 that the return codes of functions in the examples could potentially be confusing. Throughout the API and internal functions we use 0=failure/1=success, while for the main function and (exit(...)) it’s the other way round, i.e. 0=success/1=failure. We could use EXIT_{SUCCESS,FAILURE} (defined in stdlib.h, see https://en.cppreference.com/w/c/program/EXIT_status) for the latter instead for more clarity.

   See e.g. https://github.com/bitcoin/bitcoin/pull/9067/commits/4441018d0860fce64ee74fa78da79bbb21114ca9 for a comparable change in Bitcoin Core as orientation. This could be a good first issue.

2. 
   real-or-random commented at 12:46 pm on September 27, 2024: contributor

   Concept ACK

   I had the same thought in the past.

   My suggestion to remove assert() in the examples is slightly related and could be addressed in another commit in the same PR that would resolve this issue here.

3. real-or-random added the label user-documentation on Sep 27, 2024
4. real-or-random added the label refactor/smell on Sep 27, 2024
5. real-or-random added the label good first issue on Sep 27, 2024
6. 
   Cheapshot003 commented at 1:11 pm on October 14, 2024: contributor

   While working on this I noticed a mistake(?) in the comments in the verification section of ecdsa.c line 95 and 101 (probably other examples too).

   https://github.com/Cheapshot003/secp256k1/blob/01b5893389efe6615d9ec2ee5f7f0f46c44b1c41/examples/ecdsa.c#L92C1-L102C6

   The comment says “This will return 0 if the signature can’t be parsed correctly” however the return value in case of failure is 1. Shall I just adjust it together with the other return values and replace it with EXIT_FAILURE?

7. 
   real-or-random commented at 2:31 pm on October 14, 2024: contributor

   The comment says “This will return 0 if the signature can’t be parsed correctly” however the return value in case of failure is 1. Shall I just adjust it together with the other return values and replace it with EXIT_FAILURE?

   I think what is meant here is that secp256k1_ecdsa_signature_parse_compact (and the other called function) will return 0 in case of failure. (And yes, then the main function in the example will return 1, which is precisely demonstrates the confusion described in this issue.)

   But yeah, the fact that you misread this is proof that this is misleading and should be improved.

   Shall I just adjust it together with the other return values and replace it with EXIT_FAILURE?

   That sounds reasonable, yes. At the risk of stating the obvious, it makes sense to have multiple independent but related commits under the same theme in a single PR, at least if they’re small. And in this case, the overarching theme of the PR would be “Clean up examples and make them clearer”. An exception can be warranted if some of the commits are more important/more urgent, and we want to make sure that these get in and are not held up by lack of review or required changes in the less important commits.

Contributors
theStack real-or-random Cheapshot003

Labels
user-documentation refactor/smell good first issue