A name should carry the meaning

In one of our products we connect a PC client program with embedded servers over Ethernet, using TCP/IP sockets. The PC client does not want to know much about the network, so we use a router to take care of the socket connections. We call this component "Router". The PC client which talks with the embedded systems via Router, has calls to send messages and has callback for reception of messages. This works fine, and the callback will also inform the client when there is a problem, so that appropriate action may be taken. On the first version of the Router, the write call returned status of how it went: success or failure. This was OK, but what if someone unplugged the connection at a state where nothing was written? This may be the case in event-driven systems if you wait for an event forever. We actually did this, since we had introduced a subscriber mechanism.

We subscribe to data, and they arrive when they are ready. The producers, however, sit on the embedded servers - how should they inform that the cable to the PC is broken? You can't yell across a broken cable. Our solution was not good enough, so we introduced a new status return value from the Router: CONNECTION_DOWN. This could be a return value from writing as well as from the callback. Fine, out with the cable, and the user on the PC side gets notified! But, after a while we noticed that sometimes we didn't get the connection connected when we restarted the units. A smart guy discovered that it never worked if the PC client tried to connect to the embedded server before the embedded server had come around to send its "here I am" message to the Router. The problem turned out to be with the newly implemented CONNECTION_DOWN, which meant, correctly, that the connection had indeed gone down, after having been up.

But it had been coded as also meaning that connection was not up to start with. In Router, there was no option, no status was kept in it about the state of a future contender, a good design. "What is the state of Peter" could only be replied in the negative since Peter had not connected, and was thus unheard of. It turned out that we should have been more accurate with naming the CONNECTION_DOWN value, we should have called it NOT_CONNECTION_UP. The first has a history to it, the second does not. Not up means 1.) not yet connected, but also 2.) gone down after having been connected. We had to recode the client, not the Router, to contain local state of the history of the connection, so that NOT_CONNECTION_UP would be accepted before any successful communication, but not accepted after things at least once had been fine.

In programming, naming does a lot, because in the deepest sence it reflects our understanding of the problem.

01.2004