Don't Get All Your Code Thrown In The Dumpster (Fire)

There is a very disturbing trend getting worse and worse this past decade.

It first started to stand out from "the usual" development gripes about 10 years or so ago, and has been getting worse and worse with each passing year.

These issues basically make it nearly impossible to quickly, or safely, add new features or increase capacity scale without a complete rewrite.

• Little-to-no design documents
• little-to-no code comments
• little-to-no overall documentation
• lack of any clear use-case design principles
• lack of use any design patterns
• lack of code review / peer oversight
• horrific spaghetti code
• lack of QA
• riddled with terribly time-consuming bugs
• lack of any concept of security

Generally this means it is much more economical for time, resources, and finances to just scrap the whole code base, take what was learned from the incompetence of the previous group(s), and start over fresh following proper code design, implementation, and testing principles.

I have been on a number of projects over the years where the upper executive levels didn't believe me that it was best to start over if they wanted to make their deadlines.  And in many cases we just had to live with the nightmare dumpster fire we inherited.

However, in some of the enterprise and multi-national projects I've worked on, because the finances and staffing were very flexible, but the timeline and features were not, I talked them into letting us either scrap it all and start fresh, or in a few instances I talked them into letting us run two separate teams to resolve the issues, so that the best chance was given for meeting an immutable timeline.

In the few cases where I talked them into 2 (or more) competing teams, we had one team trying to work with the existing code base (often the people that created it, but sometimes a fresh team of more senior staff to try to take over and save it), and the other team starting over from scratch but using proper methodologies.

EVERY SINGLE TIME THE SECOND TEAM COMPLETELY BEAT THE FIRST TEAM'S DELIVERY DATE.

And the second team delivered an exponentially more manageable, extensible, and scalable platform that was much easier, safer, and faster to add new features and scale vertically or horizontally (or mixed) as appropriate to the needs of the company/project.

Avoid Analysis Paralysis, But Iteratively Approached Design First Is Far More Efficient and Scalable Than Code First!

The main complaint about design first is strongly correlated to a lot of "analysis paralysis". I've caught myself having to stop making it perfectly designed (I'm reminded of The Architect from The Matrix: Reloaded), and just get it "good enough and iterate later" in the design and documentation.

At least with this approach it is quick and dirty, but explains what they heck you are trying to do, so that in the future is is exponentially easier to go back later and improve things.

I often work with teams all over the world in many languages, and verbal stand up meetings cause a lot of accessibility issues related to language comprehension, etc.

Instead, using as many effective communication tools and documentation, it is much easier for diverse teams to take the documentation and turn it into code, that will work and fit the other puzzle pieces of the other developers much more neatly and effectively.

MORE TO DISCUSS HERE...

The Fallacy of "Good Code is Good Documentation"

For all those people who state that the code the documentation, you are automatically setting up your project and code base to be a dumpster fire sooner or later.

The code cannot tell you what the developer was trying to do, it can only tell you what it is actually doing, which may not be at all what is desired for that feature or performance issue

Imagine all of the developers died, or you are taking over the code base X years later

I have experienced variations on these scenarios.  All of the developers are gone (fired, quit, dead, etc).

Mission critical needs aren't being met, and the existing code base must be worked with (no option to dump and replace).

Almost zero documentation (generally just from the sales or management people, very little to none from the technical side).

Zero to no comments through the entire code base

Extremely convoluted data wrangling in the code (again with no comments or documentation explaining why they did so many hurdles).

Tons of dead code no longer even actually doing anything except that it does run and use up processing, storage, and memory resources, and in some cases causing bugs for a feature that was never actually fully implemented or since abandoned.

Or a developer comes back to their code years later, they have completely evolved, grown and changed (hopefully) as a developer, and staring that their own code, they state "I have no friggin' clue why I wrote it this way or what I was trying to do" (I have heard this hundreds of times).

The list of scenarios goes on ad infinitum, ad nauseum.

MORE TO DISCUSS HERE...

# USE PROLIFIC CODE COMMENTING INTELLIGENTLY!

Please for the love of all you hold dear, comment your code prolifically, but do so intelligently not mindlessly.

Except for complex algorithms, it is not helpful to just explain what the code is doing. We know that from just reading the code.

You need to describe what are the goals (and where applicable), use cases, design patterns, methodologies, etc.

Here is an example of an almost useless code block comment (although, if they accidentally did reverse the code, this comment would actually be helpful for finding out why there is an anomaly, because it is "perfectly good code" doing what it was told to do, but not what was actually supposed to be done):

# The get function is a generic function used to perform a GET request to a specified URL and retrieve data of a specified type .

Not very helpful, but still better than nothing in case they munged even this basic task. Without the comment, they may have written beautiful code to achieve their goal (whatever it was), but it may not actually be doing anything that it is supposed to be doing.

What we need to know is what you are trying to do. For example, if you state (in each meaningful block of code):

# Attempting to convert from Integer to String and then make comparison because DB had legacy of Zip Codes numerically, but now we're global and need alphanumeric comparison operations instead.
# I am using X design pattern to resolve this issue.
# I originally tried using library xyz with call abc, but that was leading to heavy hit on resources.
# I found this reference of code snippet that is working much better:  https://url.to/example-code-used.
<code here>

THAT IS MUCH MORE HELPFUL INFORMATION!

Another example that is somewhat less verbose, but still much more useful than no comments or the first basically useless example:

# The function searchForPartsWithTheSameMPN performs a search for parts with the same MPN (Manufacturer Part Number). It takes a string, coordinate, miles, and a completion closure as input parameters.

This is at least useful from a functions/class overall documentation statement, and can allow auto-doc tools to generate somewhat meaningful code docs, and for tracking down any wackiness in some specific areas where bugs are happening, this will make it faster to find where to look in the code base (besides what the IDE, de-linters, and other tools may (misleadingly) point to).

Don't Fall Into the "Hold Your Company/Client Hostage" for "Job Security" Fallacy!

Don't be afraid to share the struggle you went through to get your code to do what you wanted.

There is too much trying to hide the "magic" to cause artificial dependency on the developers, by holding the company hostage, some call it "job security".

However, I have seen, and also been responsible for firing thousands of developers for doing exactly that, while hiring, promoting, and increasing the pay of those who instead "do it right".

MORE TO COVER...

 About The Author

Hawke Robinson is known as "The Grandfather of Therapeutic Gaming", and is CIO, vCTO, CEO, Executive Director, Primary Investigator (lead researcher) and founder of a number of companies in a variety of industries from Health Care, Recreation, and Gaming, to Manufacturing Supply Chains, Machine Learning, and Neurotech.

In the author's own words about self related to this article:

"I am usually the guy people turn to when they want to try to accomplish "the impossible" or to overcome a project/platform/company that is completely stuck and/or on fire. I have been an innovator and troubleshooter in dozens of different industries.

I have been part of many slow and fast growth start ups, SMBs, and multinational enterprises, including Fortune top 10, 100, 500, and 1,000 companies.
I have worked at almost every level and area of the tech industry over the decades. From hands-on grunt to CIO/CTO/CSO/etc., and everything in between. I am almost always "wearing many hats" and having to work at all layers and levels of technology and business solutions.

I have been through a lot of ups and downs from successes and failures in technology, business, and community endeavors at all levels.

I was first online and coding around 1979 (yes, just 8-9 years old) thanks to family at the University of Utah giving me access early on. I had my first paid programming gig around 1982 (a POS and inventory program for a small video rental store on an IBM PC), it "only" paid around $600 initially (that would be around $2k USD in 2023), plus a few hundred more for some support initially, though they didn't really need it more than just training them to use it and to fix a few minor bus, they ran it for years after that."

 References

https://community.codenewbie.org/delia/the-pasta-theory-of-programming-39gl

https://medium.com/@eltocino/code-spaghetti-prepping-for-a-convoluted-legacy-code-base-in-react-js-c596bed1cf8c

https://softwareengineering.stackexchange.com/questions/155488/ive-inherited-200k-lines-of-spaghetti-code-what-now

https://www.bmc.com/blogs/spaghetti-code/

https://www.quora.com/Is-it-accurate-to-tell-a-programmer-they-wrote-spaghetti-code-when-the-person-wrote-a-very-long-code-in-one-file

https://hackernoon.com/javascript-the-apocalyptic-dumpster-fire-that-has-coders-begging-it-to-stop

https://www.shortcut.com/blog/letting-go-frustration-first-step-tackling-legacy-code

https://www.reddit.com/r/cscareerquestions/comments/u88jkx/dumpster_fire_code/

https://news.ycombinator.com/item?id=32963907

https://www.urbandictionary.com/define.php?term=spaghetti%20code

https://guides.lib.berkeley.edu/how-to-write-good-documentation

https://martinfowler.com/bliki/CodeAsDocumentation.html