## Embedded Alchemy

Send feedback »

Alchemy is a collection of independent library components that specifically relate to efficient low-level constructs used with embedded and network programming.

The latest version of Embedded Alchemy[^] can be found on GitHub.
The most recent entries as well as Alchemy topics to be posted soon:
Alchemy: Documentation[^]

I just completed my Masters Degree in Cybersecurity at Johns Hopkins University. I plan to resume Alchemy's development. I plan to use my newly acquired knowledge to add constructs that will help improve the security of devices built for the Internet of (Insecure) Things.

## Code Rot

Send feedback »

### What is code rot

A.K.A software rot, code decay, code entropy; there are many similar names.

Code rot: A term used to describe the quality of source code as it changes over time and migrates further away from the orignal design. This may continue until the code is no longer viable. A passive use of the term code rot describes the source code for an aging system that require dependencies or tools that are no longer available. Eventually the hardware fails and there is no way to update or port the software to newer tools.

This entry will focus on the former variant rather than the latter because it describes active code rot. Each and every change to software can introduce decay. Please recognize that rot, decay, and entropy, these are all just another word for risk, which is the potential for a problem to occur.

### Divide and Conquer

The way we build computer programs is with Divide and Conquer. Take the problem at hand, and break it down into a set of simpler problems, and work towards solving the simpler problems. Continue this process until you reach a level you can instruct the computer with your implementation language of choice. Take what is complex, and rework it until it is simple. Essentially we build a codebase one line at a time.

Every change to a program should be intentional and add value. Because every change has the potential to add the risk of new defects in the program. Unmanaged risk in development will eventually be realized as bugs. Consider yourself lucky if the bug presents itself immediately. These potential problems will linger in the code and collect silently over time. Until one day, when changes are added that start to expose these lingering problems. If this process were given a name, I would choose something that meant the opposite of Divide and Conquer,  possibly Multiply and Fail. Essentially every change becomes a new factor to multiply into the myriad of ways the code will eventually fail.

### Rotten Code

Bugs aren’t the only potential problem  that can be introduced. The quality of the code and design can be  compromised as well. This is actually what most developers are referring to when they say code rot. This is the point where adding the most minor change cannot be made without causing one of these hidden bugs to appear, or a relatively significant amount of code is required to implement a minor feature.

It does stink to work in rotten code. Rotten code can turn a new and exciting assignment into a nightmare. It’s difficult to tell how rotten code is unless you actually jump in and navigate through the morass of structured gibberish. Unless you are in the code, you also do not know what qualities and hidden gems remain from the original design and implementation. Therefore, it is very important to trust and guide the engineers that are the most familiar with code to help you make good decisions regarding change.

### Change

Change can range from the addition of a minor feature, to a major refactor, or an entire rewrite and integration of a module. Change for change sake is never a good thing when programming. Each of these augmentations requires careful consideration for how and why the new implementation will be executed.

“Those who cannot remember the past are condemned to repeat it”

George Santayana

The continual change of a program is the driving force behind code rot. The amount of impatience, inattentiveness, urgency of the schedule/budget, and in many cases, plain ignorance, all contribute to how quickly code will deteriorate. One line at a time, each feature is built. One object at a time, swaths of code are rewritten to combat the filth that seeps into the program. The only problem is, too many developers are quick to declare “This code is hopeless,” and decide to replace it with something…else.

Learning to understand an existing implementation of someone else’s idea is not nearly as fun or glamorous as designing and developing your own idea. However, there is generally always something to learn from existing code. The lesson may just as often be an example of how not to implement something. Previous mistakes are not bad, as long as you only let them happen once. It’s even better if you can develop enough wisdom to recognize a mistake that you have not made before, correct it, and avoid making that same mistake in the future.

### Boundaries

Boundaries are an under-appreciated design principle in software. There are many types of boundaries from the obvious, interfaces, objects, modules, and function calls to the not-so-obvious concept of control scope. Consider the potential value a boundary can provide. Have you used boundaries in all of the contexts listed below?

• Simplify implementations by enforcing the divide phase of our divide and conquer implementation process.
• Become a barrier to prevent rotten implementations from spreading
• Conversely, use the barrier to isolate code so it can be repaired
• Reduce the coupling that tends to causes code to become unnecessarily rigid and complex:
• Hide implementation details to minimize assumptions that cause side-effects
• Prevent direct coupling to the implementation
• Protect the integrity of the design by protecting the integrity of the data
• Use scope boundaries to:
• Limit access
• Perform automated cleanup
• Optimize
• Provide security or robustness with trust
• Protect Intellectual Property

Can you think of any uses that I did not list?

Boundaries are not the only solution to prevent and fix code rot. However, they are the simplest solution that I am aware of that are so versatile and can be used in many different contexts. Next time you consider violating a boundary so you can easily access a some data, think of code rot. It is the collection of these quick fixes, and the unintended side-effect that they introduce that allows rotting to fester and thrive. Hopefully it will help keep your code clean, tidy and a joy to work in.

## Controlled Access of Global Data

Send feedback »

Global variables have a way of becoming a binding element that tightly couples modules. Certain desired behaviors may only occur because of side-effects created when the value of the variable is changed. Conversely, undesired features seem to intermittently appear in ways that cannot reliably be reproduced. As more global variables that are added to the source code base, the system seems to become more unstable. At this point, removing or altering set of global variables in the system becomes a monumental risk, rather than a safe and simple task.

It is not realistic to simply prohibit the use of global variables. There is a reason that global variables still exist in programming languages, they serve a purpose. Just like every other feature that a language provides, it is important to know how and when to use the feature appropriately. Global variables are no exception to this rule. They can be used safely and effectively with a few practices.

Although the majority of the code examples on this site are in C/C++, the concepts and principles can be applied to any language. The most important thing to remember when adding global data, is to control access to the data. This rule applies regardless of whether you intend the data to be private to the current compilation unit, or truly global to the entire program. The most reliable way to accomplish this, is to only give access to the data through a function call. Controlling access with a function provides a control point to manage change in your application. This keeps your application flexible and able to adapt with change rather than break and have to be reassembled.

C++

 size_t g_count = 0; size_t GetGlobalCount() {   return g_count; }

The code above is fine, except access to the global variable is still not protected. There are three ways to protect access to the data at a global level without using classes.

### 1) The static qualifier

Adding the static qualifier to a global variable will tell the compiler to only provide access to this variable from the current compilation unit. This method works in both C and C++:

C++

 static size_t g_count = 0;

Be aware that a problem can arise with this method if two different files both declare static variables with the same name. The linker will complain about multiply defined symbols.

### 2) Use a namespace

This is the recommended method to limit the scope of access to global variables in C++. The unnamed namespace places the global variable in a scope block that is only accessible to the current file. Therefore, even if multiple files declared the same global variable and placed them in unnamed namespaces, the data would be viewed as a multiple variables to the linker:

C++

 namespace // unnamed {   size_t g_count = 0; }

### 3) Use a static variable within a function

This method has the advantage that the global variable is not accessible by methods inside the same compilation unit as well as other compilation units. The drawback is that a reference or pointer to the static function variable to be useful or input parameters to the function dictate how the value is manipulated.

C++

 size_t& GetGlobalCount() {   static size_t g_count = 0;   return g_count; }
Or

C++

 size_t GlobalCount(size_t value, bool isSet) {   static size_t g_count = 0;   if (isSet)     g_count = value;     return g_count; }

### Conclusion

Global data is considered by many to be evil. Often times it is necessary to have some sort of globally accessible data. Regardless, if access to the global data is properly controlled, global data can continue to be an asset rather than a liability. The key concept, which is the ability to adapt, has been given to the global variables. Access to the data is controlled completely by you. Therefore if a change needs to occur, you still have the flexibility to make your change without this becoming an engineering nightmare.

## Introduction

Send feedback »

This is a journal for those who feel they have been damned to live in a code base that has no hope. However, there is hope. Hope comes in the form of understanding how entropy enters the source code you work in and using discipline, experience, tools and many other resources to keep the chaos in check. Even software systems that have the most well designed plans, and solid implementations can devolve into a ball of mud as the system is maintained.

Software maintenance is definitely a misnomer. Once the system has been tested and delivered, any further changes are simply another round of design and development. Unfortunately, Software maintenance is typically left to junior level developers in order to free the senior level engineers to move on and make the next shiny object. When in fact, I believe the re-engineering of a software system should be led by the most skilled engineers of the organization.

In my experience, a set of newly developed code tends to hold its original design integrity for about 12-18 months after the original phase of development has completed. After this amount of time, the original vision seems to get lost, schedules become king, the original developers have moved on etc. These are some of the many reason that code seems to rot. There really is no single force to blame, just as there is no single fix to prevent this from occurring either.

I had been a software engineer for more than a decade before I realized that much of the code that I have written was really horrible, at least from a maintenance, or re-engineering point-of-view. Up to that point in my career, I usually found myself working at a new company every two years. This seems to be a common trend in this industry given the high-demand for good talent, volatility of technology startups and the enormous amount of opportunity that exists. The only problem is this never put me in the position to live in the filth that I had just helped create. I actually have found that once I was put in this position, it became a great opportunity for learning and honing my skills for this craft.

I will continue to document various experiences, tips, tricks, practices, tools, mantras and whatever else I have found useful along the way to become a better engineer. Now, with very little extra effort, I write each programming statement as if I will be continuing to re-engineer this same set of source for many years to come. Please continue to visit and learn, as well as share your experiences and practices that you have discovered for software maintenance. I also welcome any questions.

Best Regards,

Paul M. Watt

Contact / Help. ©2017 by Paul Watt; Charon adapted from work by daroz. CMS / cheap web hosting / adsense.
Design & icons by N.Design Studio. Skin by Tender Feelings / Skin Faktory.