Re-introduction to Python - part 6. Retrospective.

In this lesson we will review. And meditate.

It's always good to go back and review your code now and then. In industry, there is rarely an opportunity to do this. You are usually paid to build new features and add new code and no one has time to go back and review. Which is unfortunate, because unless you are continuously reviewing and reinventing your code, it soon becomes dead code. One of two things happen to dead code. It either crystallises into a beautiful, stable structure, which reliably does what it's expected to do forever more. Or it rots away into chaos. The latter is far more common than the former.

It is true, some code can live to a very old age. There are software tools which have been written so well that they continue to serve their purpose reliably for decades and the original code hardly needs to be touched. They are usually relatively simple tools (although there are one or two remarkable exceptions as well - see for example Donald Knuth's typesetting system TeX: https://en.wikipedia.org/wiki/TeX )

Ignoring the stuff of legends though, in most software built today the commonly accepted wisdom of "if it works don't change it" does more harm than good. Because "it works" is a very low standard. And "don't change it" typically comes from a place of fear and lack of understanding.

Yes, software development can be boring work and you will sometimes be paid good money to keep things boring. But good software engineering requires a dash of boldness.

So, unless you are paid to be boring, I would strongly encourage you to go back and review your code, from your newer, broader, better informed perspective.

Clean it up. Make improvements. Add better, stricter type annotations (and make sure MyPy is still happy). Delete code that can be deleted (this is my favourite part!) But more importantly, re-think. Re-invent. Ask deeper questions. Why was this done the way it was done? Why did it need to be done to begin with? Is it still needed? Have the requirements changed since then? Is there a simpler way to do it? Can we get away with not doing it? (the most reliable code is code that doesn't have to be written!) Can we generalise it? Is there a more general solution that can perhaps solve multiple related problems we are having - or are likely to have in the near future? Can we write a little bit of new code which can replace a lot of old code?

There is a common misconception that reviewing and rewriting old code is too costly because it takes too much time. Experience teaches otherwise. More often, what is too costly is ignoring existing code and piling up more and more functionality on top of it until everything becomes so interlocked and muddy that it becomes nearly impossible to make any changes to existing code. This slows down progress and brings projects to a halt.

When talking to engineering leaders and CTOs at organisations where software systems have been built in-house for many years, this is the single biggest challenge I keep hearing about. The story typically goes something like this:

"Our software must continue to evolve and support new capabilities, but the codebase has been accumulating more and more complexity over the years to the point where it is beginning to fall apart under its own weight. Making steps forward is becoming increasingly expensive; legacy design decisions (sometimes of mysterious origins) are holding us back; and the code is now far from a joy to work with. "

This tends to happen when maintaining code quality is deemed a costly activity and is habitually postponed or neglected.

If instead you make a habit of regularly reviewing old code and asking the sorts of questions we asked above, you will become one of the rare, valuable software engineers who bring real strategic value and uncommon insights to any project. In other words, you will become indispensable.

So I'll leave you to review your code and to ponder and discuss these questions. Here are some more topics to research:

What is "tech debt"? Why is that a thing? What are some ways of managing it?
What is "spaghetti code"?
What is "cruft"?
What is "refactoring"?
Read and discuss Martin Fowler's article "Is high quality software worth the cost?"