Specifications, part I

Great software is often being developed by several people over a long period of time. So developers use a code written by colleagues, and write a code to be used by colleagues.

There are few rules following which can help you be friends with the fellow using your code. Let's start with one important thing which is often neglected:

Your code should have specification

What is the specification of a code? It is the statement about what does it do, and how to use it. For a function, it consists from the signature, well chosen argument names, and the documentation. And in really-really trivial cases it can be the implementation itself.

Here is the list of things I want to know about your function:

• What does it require to operate properly? (preconditions)
• Does it throw exceptions? Which and when?
• What is run-time and space complexity of the code (where applicable)?
• What does it return?
• What visible side effects does this function have?
• For your function (or member-function) template, what are constraints on template parameters?
• For virtual member-function, how should it be overriden?
• Is it something special I could benefit from knowing about?

(I am living mostly in C++ Land, and not everything here is applicable to every programming language.)

There are numbers of benefits of having clear specification:

• Your code becomes more flexible -- now your clients depend on the specified contract, not on accidental details of the implementation;
• Client code becomes more correct -- now they know what to do and what to expect back;
• If becomes clear what can you silently change in the implementation, and what requires reviewing of all your clients;
• Thinking about this stuff up-front will improve your design and make your code more testable;
• You will improve your karma, and reduce overall entropy in your project, our industry and as the consequence, in the whole universe.

Function's implementation should always follow its specification. If there is a discrepancy, your clients would not know where is a bug -- in your specification, in your implementation, or in their implementation, -- and they would trust neither, and they would be sad. It's not fun to work with the code you cannot trust.

No, that doesn't mean every function in every project should get its page-long doxygen-comment. Come soon to read next part on that topic.