Question

For the most part, the library I’m developing is going to be consumed internally by one or more projects. With that in mind, should I add logic that performs type checking on all parameters for functions I write, on some parameters or none? To do selective type checking, I feel, would create an inconsitent feel to the API, to do it for all parameters would bloat the code, and to do it for none could lead to error messages that aren’t helpful. Any guidance as to why or why not would be appreciated.

Answer 1

First of all, it is important that you document your API, even if it’s only for internal use. It comes in handy if you need your code some years later.

In this documentation you can tell the user what type the parameters should be. An often used tool for documentation is doxygen:

/**
* \brief Converts a string into a DummyObject
* \param str should be a valid string
*/
function str_to_dummy(str) {

}

/**
* \brief Converts an object into a DummyObject
* \param jsobj should be an object which contains at least
*        the following attibutes: 'height','length', 'size'
* \example json_to_dummy({'height': 12,'length': 15,'size': 11});
*/
function json_to_dummy(jsobj) {

}

Keep in mind that the user will experience an error message either way, either:

Parameter 'o' must be an object with attribute 'height'

or

ReferenceError: o.height is undefined

While it is nice to get a more verbose error, it often isn’t necessary if you document your API correctly.