Looks Like a Duck?

Alley Cat (1983)

Every once and a while I needed to create something new. In reality, though, it never seemed so: there were past work done in related field. People were thinking of it, writing code, and might also think they did the best possible work there. Those people do not seem stupid, right? In fact – they might even seem geniuses at this time! After looking at their work, I found it extremely hard to understand the theory and code design. Hmm..  If that is the case – they are clearly far smarter than me. The only logical conclusion I had, is that I should be extremely careful, avoids making big changes in the design, and spend the team’s best minds and effort in understanding and maintaining this puzzling gold. Thankfully, at some point of time I woke up and understood the legacy code and theory. In many cases - it was crap, made hastily by (usually smart) flesh and blood people - just like me. But the time it took me to acknowledge this reality, was far too long and expensive

Control console of a Russian nuclear power plant - don't touch!  

No one wants to do unnecessary work. And managers will always strive to consider a model where the feature is already implemented and only some slight maintenance is enough. The decision to implement something from scratch is a scary one: it will take time, and if you don’t care for the details – then why would you thinks it will be better this time? If it works 80% of the times – maybe just make small fixes?

When you need to take ownership on existing work you are instantly transformed into the underdog. Just a day earlier, you were the genius technical authority managing your previous tasks. Today you woke up to be the stupid manager that does not understand the basics. This challenging period is where you will need to utilize your crap smelling abilities

• Don’t just jump directly to the code or API references. Try to find some paragraphs that tell ‘the story’ of the module and its usage, or even someone that could explain its logic. If he cannot explain it to you in simple down to earth words it’s a bad sign.
• It is really rare to find technical ideas that are too hard to be explained to an engineer. If you and your team try hard to grasp the basic concept and still don’t see core idea – it’s a bad sign
• Can you find sense in the interfaces and naming?
• Unreadable codebases are common. Try to send an engineer to reverse engineer it – or even do it yourself. Take a sheet of paper and sketch the different classes and their relations. Try to recreate the design diagrams: class diagram, instance diagram, sequence diagrams, etc. If that is too hard – it’s a bad sign
• Code with many dead branches or undocumented states and if statements
• Did you analyze some large and complex modules, that after a week of trying to understand its work – you discover it’s doing a trivial task? ( Such as (a+b)/2 )
• Think what it will need in order to implement it from scratch. You can take an hour and sketch some quick design diagrams and see if it makes sense. If the decision is extremely hard – consider sending an engineer to a ‘pilot’ where he will implement it from scratch in a few days. It might be that once you observe the pilot work you will already feel it is better. Taking hard decisions is easier once you get this information

No matter how much I will discuss it – this repeating dilemma is related to your wisdom and experience. You can’t fix that by reading a book. My 2 cents here are the suggestion you will acknowledge the critical issues on crap smelling, and consciously work to tune your natural instincts - and try to improve over time.

I certainly don’t suggest you treat every legacy code as crap that requires rewrite. Instead, try to find your own balance, and acknowledge the effort you will need to make before taking such a critical decision.