The High Cost of Misunderstood Code

“There’s no such thing as a free lunch.”

There never was.
There never will be.

It has become a common phrase to warn consumers of the hidden costs of seemingly free products.

As a software engineer, I see a different meaning in this phrase.

From my firsthand experience, whenever it comes to learning how to build or implement something new, foundational, or complex, a simple, free tutorial isn’t going to be sufficient.

You may find that these kinds of aids are counterproductive to the health of your team, project, and codebase.

Why?

It isn’t necessarily the content itself but how one consumes that content.

Understanding “how” to do something foundational and complex is only part of the picture. One must also understand the “why” to be successful.

The Problem

Imagine a civil engineer performing math calculations to ensure that a given bridge design will support an expected amount of weight.

If he or she fails to understand why one should use a specific formula in a given scenario and why they work that way, their understanding of how to apply them properly significantly diminishes.

In this case, the consequences could be disastrous.

I have seen a similar problem arise in my software applications.

One of several examples that I commonly refer to is properly passing data from one step onto the next in an RxJava call chain.

If you only learn the basics of flat mapping from a quick tutorial, you’ll have a working sample but won’t understand how to avoid the pitfalls of threading and mixed scopes.

To fully understand the proper application of this technique, you must comprehend further aspects of RxJava streams.

The Fallout

It is rare to only use an essential or foundational concept once in application development.

Unless these practices are well thought out and fully understood, the cost of misusing or misunderstanding them can be very steep because you and your colleagues will continue to apply that pattern time and time again.

I hear many of my teammates tell me that they learn how to do something by looking at another example of it in use within our app. That is perfectly normal. I do the same thing.

What if the person that implemented that example lacked the same understanding as the one currently investigating how to do it?

One would expect the same pitfalls and lack of understanding to be propagated repeatedly.

As with anything, the more time and energy you invest in something, the harder you’ll find it is to unwind should you ever need to backtrack.

The Solution

Simply put, the solution is to stay abreast of current technologies and techniques.

That involves lots of reading (or watching videos) and proper involvement in the right communities.

Since I am a professional Android developer, I take the time to read the platform’s documentation, and I subscribe to the relevant channels on YouTube and Reddit.

Once your internet subscriptions are up to date, take the time to invest in your understanding.

Are you working on something new? See if the platform vendor has a video or video series on how to do it.

You are setting the trend for how your team will build these things in the future. Therefore, an investment in yourself is an investment in your colleagues.

This discussion begs this question: when is your understanding complete enough to start putting it into practice? This matter is a sliding scale.

Smaller concepts would require less familiarity than a more complex topic. In general, if I can explain a given topic to one of my colleagues and answer most of their questions confidently, I know I am ready to put my newfound knowledge to work.

Cleaning Up the Past

While these ideas can be helpful for new work, what about cleaning up old work that suffers from the problem mentioned above?

For this situation, I follow a technique that I call the Model City Paradigm.

In essence, if a country wants to rebuild itself into a more modern society, it would be impractical to uniformly apply its concepts to every city, town, and village within its borders.

Thus, many countries have model cities, where their ideals are employed on a large scale for future developments or redevelopments to look for inspiration. These practices can either be fully baked or experimental.

The United Arab Emirates has Dubai.
Australia has Canberra.

This concept applies just as well to your code. Take a section of your project that you would like to update or rewrite, study the proper way to do it, and implement it very well in one area of your code.

Try to keep these changes limited to one screen or feature of your project. Then, use that section as your model code for the rest of your project.

As you have time to address the identified issues on a broader scale, look to your model code. I try to set aside at least 10% of my weekly efforts toward these kinds of improvements.

Once I’ve done that, I communicate my changes so that others know where to look for inspiration instead of copying an old, problematic technique.

Conclusion

Even though your team has always done something in a particular fashion, that doesn’t mean it is always the right way.

Staying current with your industry’s latest trends, tools, and conventions can help spotlight weak areas in your code and show you how to address them. There is no substitute for reading relevant developer news articles.

Doing so can save your team the pain of investing time in an incorrect tool or technique that is potentially full of pitfalls. Research the best way to implement your feature, fix a part of your project to follow those recommendations, and use that sample as a model for future refactorings or additions to your project.

These practices aren’t unachievable. I use them in my project and with several teams regularly.

I encourage you to try this technique. It will get you several steps closer in this direction and improve your standing, project, and team.