Uploaded image for project: 'Request For Comments'
  1. Request For Comments
  2. RFC-78

Add API error-checking to coding standards

    XMLWordPrintable

Details

    • RFC
    • Status: Adopted
    • Resolution: Done
    • DM
    • None
    • On this JIRA ticket

    Description

      I suggest that we add:

      When an API is used that provides a means for returning an error indication, the invoking code shall perform a check for errors.

      In particular, when invoking POSIX library functions or system calls, the return value shall always be checked for an error condition, and if an error condition is found, the value of errno should generally be preserved or reported in some form, unless a specific value of errno is expected as part of the normal operation of an algorithm.

      Rationale: In general it is clear that if you invoke a function, you want to know whether it claims to have done what you asked. It is true that in casual coding there are some commonly used library functions that will very rarely return an error, and there are traditions in various communities of not checking in these cases. However, in a large production project it is preferable to make error-checking a blanket rule because even extremely unlikely error conditions have a way of happening at some point, and the error check may provide the only clue for the cause of a rare failure.

      to the programming standards. I am thinking primarily of C++ but the principle applies mutatis mutandi to Python.

      Attachments

        Issue Links

          Activity

            gpdf Gregory Dubois-Felsmann created issue -
            ktl Kian-Tat Lim made changes -
            Field Original Value New Value
            Description I suggest that we add:

            bq. When an API is used that provides a means for returning an error indication, the invoking code shall perform a check for errors.

            bq. In particular, when invoking POSIX library functions or system calls, the return value shall always be checked for an error condition, and if an error condition is found, the value of {{errno}} should generally be preserved or reported in some form, unless a specific value of {{errno}} is expected as part of the normal operation of an algorithm.

            bq. *Rationale:* In general it is clear that if you invoke a function, you want to know whether it claims to have done what you asked. It is true that in casual coding there are some commonly used library functions that will very rarely return an error, and there are traditions in various communities of not checking in these cases. However, in a large production project it is preferable to make error-checking a blanket rule because even extremely unlikely error conditions have a way of happening at some point, and the error check may provide the only clue for the cause of a rare failure.

            to the programming standards. I am thinking primarily of C++ but the principle applies _mutatis mutandi_to Python.

            I suggest that we add:

            bq. When an API is used that provides a means for returning an error indication, the invoking code shall perform a check for errors.

            bq. In particular, when invoking POSIX library functions or system calls, the return value shall always be checked for an error condition, and if an error condition is found, the value of {{errno}} should generally be preserved or reported in some form, unless a specific value of {{errno}} is expected as part of the normal operation of an algorithm.

            bq. *Rationale:* In general it is clear that if you invoke a function, you want to know whether it claims to have done what you asked. It is true that in casual coding there are some commonly used library functions that will very rarely return an error, and there are traditions in various communities of not checking in these cases. However, in a large production project it is preferable to make error-checking a blanket rule because even extremely unlikely error conditions have a way of happening at some point, and the error check may provide the only clue for the cause of a rare failure.

            to the programming standards. I am thinking primarily of C\+\+ but the principle applies _mutatis mutandi_ to Python.

            ktl Kian-Tat Lim made changes -
            Resolution Done [ 10000 ]
            Status Proposed [ 10805 ] Adopted [ 10806 ]
            tjenness Tim Jenness made changes -
            Link This issue relates to DM-8655 [ DM-8655 ]
            tjenness Tim Jenness made changes -
            Watchers Gregory Dubois-Felsmann, John Swinbank, Joshua Hoblitt, Kian-Tat Lim, Tim Jenness [ Gregory Dubois-Felsmann, John Swinbank, Joshua Hoblitt, Kian-Tat Lim, Tim Jenness ] Gregory Dubois-Felsmann, John Swinbank, Jonathan Sick, Joshua Hoblitt, Kian-Tat Lim, Krzysztof Findeisen, Tim Jenness [ Gregory Dubois-Felsmann, John Swinbank, Jonathan Sick, Joshua Hoblitt, Kian-Tat Lim, Krzysztof Findeisen, Tim Jenness ]
            tjenness Tim Jenness made changes -
            Link This issue is triggering DM-9038 [ DM-9038 ]
            tjenness Tim Jenness made changes -
            Component/s DM [ 11604 ]
            Component/s LSST [ 12210 ]

            People

              gpdf Gregory Dubois-Felsmann
              gpdf Gregory Dubois-Felsmann
              Gregory Dubois-Felsmann, John Swinbank, Jonathan Sick, Joshua Hoblitt, Kian-Tat Lim, Krzysztof Findeisen, Tim Jenness
              Votes:
              1 Vote for this issue
              Watchers:
              7 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved:
                Planned End:

                Jenkins

                  No builds found.