2020-10-23 - brand new legacy code

this post is already couple of years due. but i think it is worth to tell this tale.

back at that time i was working in a project, that had a chance to define a brand new interface. totally from scratch. no legacy, no backward compatibility – whatever the person responsible for it will decide, will get implemented. rare occasion and a great moment in project's history.

the only real requirement was performance when sending large data blocks. so what could go wrong here? designing detached from reality when author of the specifications started to do changes without any experiments or measurements.

after initial draft (“message level”) it came down to encoding and transmitting. this was a moment in time where “optimizations” started to kick in. nevermind the details – mostly loads of pointless “what if” discussions, that had no support in any data. just a “strong feeling” that it will be better. however noting is for free. each of these “optimizations” added complexity and some extra states into (otherwise fairly straight forward) specification.

as you can imagine, it backfired within a year time window. extra steps turned out to be complex and error prone. this in turn caused endpoints to go out of sync, on random occasions. these issues were often non-reproducible, and timing related. after having agreement between two ends of the communication channel, the spec was pretty much set in stone.

the interesting part was to see that when deployed, the protocol had zero issues with performance. just for the sake of discussion we also stubbed the implementation with “naive” one – it did not even sweat! all the pain (discussion, extra implementation, countless bugs and nerves) – in vain. due to lack of proper measurements, that would support decisions to increase complexity, the team ended up with brand new legacy code that they had to maintain.

more over – planned ultimate-flexibility of the protocol failed, too. in fact the very first change in requirements that arrived blew the root concept apart. it just happened to hit the part of the protocol that author assumed will never change. to fix it even more extra states were needed, with even more potential for errors. on the other hand, the parts that were made flexible enough to accept any possible input, were never really needed exercised. both KISS principle and open-closed principle were violated here and it did not took long to see the results.

avoid over-engineering and bikeshedding. when making sth new stay focused on the problem you are solving. support your decisions with actual measurements. use prototypes / PoCs to help guide your research.