I believe the following happens to every seasoned software engineer during some part of their career. You have been tasked to create a new program. Or you just start to create it yourself to assist you in some time-consuming mundane tasks. You pay no attention to code quality. It is enough that it just works. So, you cut some corners. Maybe there is a new library you are trying. You fiddle around with the parameters, stick in 1, 0, NULL in some obscure order until it works. You leave in the code a lot of magics (pure numbers and symbols which do not tell WHY they have been defined as such). Because, you know, it is just a temporary debug program.
What happens in reality, at an alarming rate, is that these programs, meant strictly temporary, become actually quite permanent. In many cases they end up outliving the contract periods of the engineer originally writing them.
The curse of these programs, for the casual observer (such as management), is that they have been performing somewhat ok. Yes, there is the occasional bug report, but no mention of any kind about the totally low-grate code quality. This being the case, the odds are that even those people seeing the ingrained flaws will never be allowed to fully fix the problems, because it adds little immediate commercial value.
The options at this point are quite limited and grim. One option is just to let it be, risking the non-quality coming back and you biting your butt every now and then, sometimes even leading to more serious problems regarding development time or bug fixes. Another option is to fix things in secret, which is not an uncommon path either.
As we probably agree, the options are solutions to a scenario which should never have happened. In other words, the only thing to prevent non-quality code getting a lifespan, is to not write such in the first place. And this is exactly what I urge you to do: Don’t write non-quality code. Ever. Even if it was the tiniest little debug program intended just for you. Even if it was just a hasty subsystem mock up. Just don’t. Before you realize it, your code is in use with environments, situations and attendance never imagined.
There is no universal definition about what code quality means for every organization, but as an example already hinted in the beginning, I present a simple case I almost hate to bring up due to its mundane nature. Don’t use magic values. I will demonstrate.
Don’t do this:
Library_Function("test", true, NULL);
What does it tell you? Kind of absolutely nothing. Use this principle instead:
#define MYMODULE_LIBRARY_IDENTIFIER "test" #define MYMODULE_LIBRARY_KEEPALIVE_YES true #define MYMODULE_LIBRARY_EXTRA_PARAMS_NONE NULL
Then you can write:
Library_Function(MYMODULE_LIBRARY_IDENTIFIER,
MYMODULE_LIBRARY_KEEPALIVE_YES,
MYMODULE_LIBRARY_EXTRA_PARAMS_NONE);
It is now instantly clear what the parameters mean.
Also similarly, a memory copy example. Don’t do this:
memcpy(&au8_message_buffer, &(au8_frame_buffer[2]), 10);
Do something like this instead:
#define MYMODULE_CORE_MSG_CONTENT_START 2
#define MYMODULE_CORE_MSG_CONTENT_LENGTH 10
memcpy(&au8_message_buffer,
&(au8_frame_buffer[MYMODULE_CORE_MSG_CONTENT_START]),
MYMODULE_CORE_MSG_CONTENT_LENGTH);
Now it is again much clearer about what we are doing and why. In general we normally whip these defines somewhere in the beginning of the file after we are done with the function.
There are a lot of ways of enhancing the quality of your code. What was demonstrated here was just a mundane example. Remember: Built quality in whatever program you are working with. When done enough times it becomes somewhat automated and desired habit.