I am viewing this lecture (http://www.youtube.com/watch?v=aAb7hSCtvGw&hl=nl) and at about 34 minutes, a bullet point on a slide is mentioned stating "document state space very carefully".
What is state space? Why would I have to document it "very carefully"? Unfortunately, I have no sound on the machine I am posting from right now, but the slides themselves are extremely useful to my learning (it would be even more helpful WITH sound).
Thanks
A state space is the set of possible states, in this case of an object.
In the audio, he's basically saying that you need to document which operations are allowed in which states, and if any operation changes the state of the object (which would change the set of permitted operations). He mentions this is especially important for mutable objects.
He uses Date and Calendar from Java as examples of APIs where this is a problem, but doesn't go into specifics.
To give a concrete (but simplified) example, consider a TCP connection. That would basically have two states, open or closed. When it's closed, you can't send or receive anything through it, so calls to those methods are not permitted.
Paraphrasing what the speaker says, if the object is mutable, you need to document the state space. He then references Java's Date and Calendar API being badly documented in this sense.
I'd guess what he means is that you need to document any functions that could modify the state of the code. Also when it is a good (or bad) time to call these functions. Example, calling a read() function after the object is closed().