Question

bool is_something_ok(int param,SomeStruct* p)
{
    bool is_ok = false;

    // check if is_ok

    if(is_ok)
       // set p to some valid value
    else
       // set p to NULL
    return is_ok;
}

this function return true and set p to a valid value if “something is ok”
otherwise return false and set p to NULL

Is that a good or bad design? personally, i feel uncomfortable when i use it.
If there is no document and comment, i really don know how to use it.

BTW:Is there some authoritative book/article about API design?

Answer 1

Since you have tagged the question as C++ and not C, I would suggest you to:

• return the value directly
• if you have more than one value, use output parameters
• use non-const references as output parameter where possible (instead of pointers), and use const-references for the input parameters.
• if something went wrong, raise a exception instead of returning false or -1.

But that are just some general hints. The best way to go always depends on the specific problem…