7 Software Engineering Practices That Took Me Years to Realize
Thank me a few years down the road
I have been writing code for four years now — not that long — and I am not yet a senior. I want to share and document the things I have learned so far.
Some of these took me some time to realize. If I could go back in time, I would tell my younger self to read this. Who knows? I might be in a much better place now.
Deprecating functions is easier than rewriting them
// put a deprecation notice on the function
/**
* @deprecated replaced by {@link getMetricsV2}
*/
function getMetrics() {
// old code
return metrics;
}
// now you want to include something else in metric calculation
function getMetricsV2() {
// old code
// new code
return metrics;
}When you need to change spaghetti code, your first instinct may be to nuke a function, rewrite it, and turn it into something different. It feels satisfying and productive.
After rewriting the function, you need to update all the usage in all the files, which is still manageable.
Suddenly, your testing fails (assuming that you have any), and you discover that your fresh-from-the-oven function is the problem. You look everywhere for the issue, but it turns out that the new function isn’t working correctly.
This scenario is precisely why people with more experience deprecate functions instead of replacing them. They know that doing so won’t disrupt the existing, working flow of the application, and it’s also less time-consuming and effort-intensive.
You can either use the existing function in the new code or copy the content and make changes if necessary. If you can avoid it, try not to modify old, functioning code.
Start debugging from the source closest to you
One day, I found a problem in production that I couldn’t troubleshoot with logs since they were unavailable for some reason.
Debugging production issues without logs is like gambling. Sometimes you might get lucky, but most of the time, it leaves you feeling even more frustrated.
I reached out to several people, including those in charge of the related components, to identify the root cause, but nothing seemed to work.
My senior then advised me to try debugging the issue locally. As it turns out, there was a bug in the code, which might seem obvious, but it’s easy to assume that the problem lies with the environment instead of the code.
In such cases, it’s crucial to take a step back, eliminate all assumptions, and look at the code from a fresh perspective to identify the underlying issue.
Check for libraries, don’t reinvent the wheel
I once worked on an encryption/decryption feature, and feeling fancy, I decided to write it from scratch.
It took me a few days to implement, which was time-consuming, considering that I could have easily incorporated a third-party library instead.
When developing software, it’s essential to be hands-on, but it’s even more critical to be efficient and cost-effective.
One of the most overlooked aspects is using proven, battle-tested libraries to perform simple tasks. Using libraries can save a ton of time, which can then be used to refine the core functionality of the application, instead of worrying about implementation details that nobody cares about.
Additionally, external libraries are usually well-maintained by experienced programmers, who are more likely to be better than us. They are also kept up-to-date with the latest technologies and vulnerabilities.
For example, suppose you need to shuffle an array. In that case, it’s best to use Lodash, which will most likely provide you with additional functions as well.
Switch to a strongly-typed language
As someone who primarily worked with JavaScript, I was used to developing software that had many bugs. I would rely on my eyes and brain to catch all possible errors, which was a time-consuming and tedious process.
However, due to work requirements, I had to switch to TypeScript, which I initially didn’t like. But now, I can’t imagine working without it, and I love it.
Strongly-typed languages like TypeScript perform error checking at compile-time, and even before compilation, modern code editors can help detect potential issues. This type of checking prevents many errors from occurring during the development cycle, leading to higher-quality code.
In addition, strongly-typed languages allow developers to document their code without having to write lengthy comments. For example, in a verbose TypeScript function, you can see the name, the type of parameters, and the type of return value. If named properly, others can quickly understand the function’s purpose.
Switching to a strongly-typed language offers numerous benefits, including improved code quality, faster development, and improved scalability.
The only drawback may be that your teammates will hate you, but your managers and clients will appreciate the high-quality code you produce. In the long run, using a strongly-typed language can lead to significant time and cost savings for software development projects.
Ask seniors sooner
There have been countless instances where I’ve spent hours trying to solve a problem, only to later realize that it’s not possible.
Sometimes, as a developer, you might be hesitant to ask for help out of fear of appearing incompetent or that your colleagues will think less of you. However, the truth is that they don’t really care. As long as you don’t ask a question that you could have easily answered by a quick Google search, you should be fine.
It’s essential to understand that asking for help is not a sign of incompetence or lack of skill; instead, it’s a sign of maturity and professionalism.
As a developer, you need to know when to fight and when to submit, and seeking help is a part of that. By asking for help, you can save time and learn from others, which can help you become a better developer in the long run.
A long function name is better than an ambiguous name
Have you been afraid that your function names are too long? Been there, done that, nobody cares. As long as the function works as the name described. Long names might seem weird at first, but try it and you don’t ever want to write short function names anymore.
Long function names are more descriptive and provide more information about the function’s purpose, making it easier for others to understand the code and reuse it in the future. Some might say that it does the documentation for you.
Compare that to function name like checkValidUser(). Check what?
now try to guess what this function does checkIfUserPropertiesAreValid() .
using short or ambiguous function names can lead to misunderstandings and mistakes, making it harder for developers to debug and maintain the codebase.
Using long function names can also enhance the readability of the code, especially in complex software projects. It can save time in the long run by helping developers quickly identify what the function does without having to dig through the code or guessing its purpose.
Log properly
If there is one thing that you can get from this article, it is this. Please log your application properly.
Logging is so underrated.
Proper logging can help developers diagnose issues that occur in production and improve the overall quality of the application.
When logging, it’s important to consider the level of granularity and the type of information being logged. It’s crucial to log enough information to diagnose issues, but not so much that logs become cluttered and hard to read.
In addition to logging the appropriate information, it’s important to consider the format and organization of the logs. Consistency in log format can help make it easier to search and identify issues in production.
It’s also essential to consider the security of logs. Logs often contain sensitive information such as user data and API keys. As such, it’s important to ensure that logs are encrypted and stored in secure systems to prevent unauthorized access.
Hopefully, these practices can help you reduce errors, increase efficiency, and build better software. And who knows, maybe one day you’ll be the one sharing your own list of software engineering practices that took you years to realize.
