Damn! What is that bad smell?
The “that’s not the wallet inspector…” feeling
Have you ever had that feeling when you’re looking at someone’s code or checking a software architecture that something is not right? That even when it looks “cool” or “the others” are saying that it’s ok, you have that gut feeling that maybe a small fly crap can destroy the whole project in 5 seconds? Have you ever felt the “that’s not the wallet inspector” feeling?
If you answered affirmatively to any of my questions, you have had a Code Smell or Bad Smell experience (hallelujah! Well… maybe not). Bad smell is Miss Mommy experience and Mr daddy blood and tears talking to you, coming from the bottom of your heart. It’s like that 6th sense that developers acquire after years of experience.
There is a popular quote (usually attributed to Einstein) that says: “If you can’t explain it to a six year old, you don’t understand it yourself”. So in this post I’m going to share a story in an easy and self-explanatory way, that even a small kid should understand it (as much as possible). So let’s begin!
Chapter 1: The Knight & the Spaghetti Monster
Once upon a time, in a faraway land, a young Architect Knight decided to accept a job offer from the Nepotistic Kingdom (NK). Two years prior, the king, I-have-no-idea-what-I’m-doing AKA Big Doggo, decided to outsource their most important new product: The Holy Knowledge and Recursive Analytical Platform, or like most people called it: Holy K.R.A.P. The company in charge of the development, Dumb Ltd., resided in a different kingdom so far away that they spoke a different language, had a time zone difference of almost half day, and no real quality credentials. However, they were recommended by one of Big Doggo’s friends and — maybe the most important reason — Dumb was extremely cheap… sniff, sniff, can you smell that?
Dumb said that the project’s development would take 8 months, but 2 years later people of NK were still waiting for the product that would improve/automate internal processes and give a business advantage over the competition, specially from those new Startup Kingdoms that are showing real innovation “we have to be like them!”. Even when most Engineer Knights suggested that Holy K.R.A.P was going to fail, Big Doggo and Holy K.R.A.P’s Sir Project Manager wanted to prove themeselves, so they kept defending the product quality, even when they didn’t know how software works. Their ego was more important and bigger… seriously can you smell it?
Chapter 2: The Fresh Man Week
It was Architect Knight’s first day, and one of the first things that his boss suggested for him to do was to check the Holy K.R.A.P website, given that it was finally going to be released during the following month. Young Knight set journey into the unknown and the first obstacle he found was a login page that wasn’t redirecting to HTTPS. Something weird for a new critical product, specially when the SSL Manager Portal showed that someone had bought the certificate 4 months prior. Trying to overcome the previous obstacles, the young knight accessed the page using HTTPS and found a certificate!… but the wrong one (🤦♂). “What kind of dumb creates a Wildcard signing request (CSR) and buys a Multi-domain certificate?” — The Knight thought. The young Architect recreated the SSL and knocked down the obstacle… cough, cough.
In that same week, realising that he needed more information to tackle the next obstacles, the young knight requested Holy K.R.A.P’s architecture document. The Dumb guys came back with some autogenerated UML models with no comments or additional documentation explaining any rationale or describing non-functional or functional requirements. “This is as useful as the share button in a porn video!” — The knight exclaimed. So, Young Architect went back to Dumb and asked for a proper documentation of the architecture to fully understand what was happening, especially with the REST API. After a couple of days without any response, the architect asked his boss if he knew anything about the API. That’s when he discovered that the API was so bad, that even NK’s Sir Senior Developer couldn’t use it, so they decided to connect directly to the database to extract the data from there (even in some cases recreating logic)… lady damn! I think something is rotten.
The young Architect thought that the API situation was a bit odd for a non-released new product, so he decided to test it. Worst. Idea. Ever. Ladies and gentlemen, the ignorant demon is pleased to introduce to you, a REST API where every single endpoint is a POST method and the HTTP protocol standard doesn’t matter, eat that Tim Berners-Lee!. Not happy with that, this terrific API required every single request to include the plain user and password credentials, and — for those who love hacking shitty websites — invalid request schemas returned a response with the complete SQL query.
By then, the young Architect was running out crazy. He couldn’t believe that this could be possible in the 2010s. That’s when he decided to run the project and check the user interface… “Wait a second , I’ve been sent back to the 90s? that era when people was dancing La Macarena and the use of Windows 95 was the shit?” — The young knight exclaimed. And then he thought: “It’s just the user interface, behind the scenes maybe it’s a rocket launcher”. So he decided to read the code, which was hosted in a mono-branch SVN repository (yeah, that’s right, you read it correctly), and then… he saw hell on earth: The “that’s not the wallet inspector” feeling hit him… definitely, Holy K.R.A.P IS crap.
Chapter 3: Rise and Fall
After everything he saw, Sir Architect talked to his boss and tried to convince him that they shouldn’t release Holy K.R.A.P the following month, the risk was too damn high. His boss could only suggest that he talked to Big Doggo and Sir Project Manager, and that’s how this conversation about a death foretold went:
Big Doggo (BD): Sir Architect is saying that Holy K.R.A.P is not ready. Is that true, Sir Project Manager?
Sir Project Manager (PM): Sir Architect doesn’t know what he is talking about. Dumb is going to release it and we already verified that everything is working.
Sir Architect (SA): The API is not working, there are fundamental design errors affecting the architecture as a whole, their documentation is not even well written in their own language, and it’s a project with almost a year and half of delay. We should re-evaluate the product.
PM: You don’t know anything about the product, you’ve only been working here for a couple of weeks, and you don’t know how this business work!
SA: Well… I might not know this company’s business yet, but I know how a good system should look like, and Holy K.R.A.P is not even close to that.
BD: OK, how can we know that Holy K.R.A.P is good?
SA: I have done a couple of tests, as well as used Code Quality and Complexity Analyser software to obtain “objective” results.
BD: Perfect! Please send those results to us and we can make a decision based on that.
After that meeting, Sir Architect sent a report from SonarQube that showed close to 50% of duplicated code, 4+ years of technical debt, 24K+ bugs, 1K+ of security errors, 97K+ code smells and crazy levels of Cyclomatic Complexity… and there was no response from Big Doggo or Sir Project Manager whatsoever.
3 months later (again, not in time), Holy K.R.A.P was released! Yayyyyy 🙌 … and 3 months after that the product was frozen 😐. The new system generated financial data errors, the search engine was taking up to 160 seconds to reply, more than 5 concurrent users were freezing the system, the cost of maintaning the product was taking almost half of IT department’s infrastructure budget and the internal surveys showed that some employees were to resign if they had to keep using the product because it was “making their lives miserable”.
K.R.A.P was discarded leaving a huge financial hole that NK tried to mitigate with an internal development of K.R.A.P v2 under the command of Sir PM and Big Doggo (that project also failed but that’s a story for another time). Finally, the young architect resigned after several months of fights and handcuffed-hands situations and moved on to a new kingdom, Sir PM lost half of his team, and Big Doggo is now just a Doggo. And Snip, snap, snout, this tale’s told out.
Lessons of this story
- There are no heroes or villains. Big Doggo and Sir PM are not villains, as well the Architect Knight is not a hero. Why? No one won! There were only losers: NK and it’s employees.
- The effects of bad decisions are only reflected in the mid/long term. The problem with the worst decisions is that most of the time they look perfect in the short term, but always remember: “time is a bitch”.
- Do not let the ego and friendship drive your decisions and objectivity. Nepotism is one of the biggest issues in most companies. How do I know that a specific person is the best option for that role? Are my friends or family the best options? Do not misinterpret me, sometimes you have brilliant friends that you know they’re gonna do the job, but how many of those do you know? Are you willing to pay for them? As a professor of mine used to say: “It’s not that there’s no talent, it’s that you don’t want to pay for it”.
- Listen other people’s opinions, specially when you are not an expert (and even if you are). It’s not bad to be an ignorant in certain topics. Keep learning from juniors and seniors, every single person is an open book.
- If you feel that something is wrong, keep searching. Sometimes one issue or two don’t mean that the whole thing is wrong. Bad decisions, most of the time, come from mediocre mental processes, so do not rush it and always follow methodical procedures to detect/analyse problems.
- Multiple or extreme delays in delivery, cheap team and a visible Conway’s Law are clear symptoms of Bad Smell. As Conway states: “organizations which design systems … are constrained to produce designs which are copies of the communication structures of these organizations.” So if you have a cheap and disconnected team, you already know how your system will be.
- Always support your arguments with an engineering/mathematical procedure. There are tons of methods, theories and tools that can help you estimate and manage the risk. In the case of software, you may find tools for multiple purposes that can assist you detecting code smells and possible technical debt.
- Sometimes it’s better to accept that something is not working and stop on time, instead of waiting until the last moment. I know it’s hard to accept that you failed: your reputation and ego will be affected (and most of the time money too). But as Oscar Wilde once said: “Experience is simply the name we give our mistakes”… so learn from them and embrace them!
