Tuesday, November 1, 2016

A Spec File Should...

When writing a spec for an interface (public facing functions/methods of a software module/api) and that spec is written in the same language and that spec is a runnable test that executes the module...it is a fantastic way to show others how the module should work and how to use the interface...so the spec should be written in a way as it conveys these things to the reader.


Imagine a spec written for a users API. And that API has a method to getUsers and that spec has the following description:


"it should all active employees"
and the API is exercised like this:


getUsers(true);


How safe is it to assume that the first input parameter is isActive. Or could it be null? Or some other flag?


To remove ambiguity in the spec, ALWAYS pass named variables...


includeInactive = false;
getUsers(includeInactive);


yeah, yeah most editors and IDEs show the variable name somehow. Not always going to be accurate, or clear, or built yet (write the spec first anyone?).

No comments:

Post a Comment