Effortless Maintenance: Personal Tips for Making the Maintenance Phase Painless

Have you ever heard the saying, “If you don’t fully understand how it works but it’s still functioning well, leave it alone.”? While this may not always be true for other things, it often reflects the reality of the maintenance phase in the IT industry. Why is there an odd thought like this?

Imagine that if you’re fortunate enough to be the one fixing something you originally built, it’s easier because you’re familiar with the techniques you used and where you might have hidden tricky bugs. In reality, however, IT projects are frequently outsourced, meaning we usually engage with them only for a short period during their lifecycle. When it comes to maintenance, you might often hear or even say, “It’s usually easier to build from scratch than to fix existing code.” To improve the experience for our colleagues who have to continue with the maintenance phase, let’s consider what we can do to make their tasks easier and more manageable.

1. Pure function

A pure function is one that always returns the same value when given the same parameters, is not influenced by external factors, does not cause any side effects, and is as simple as possible. Ideally, each function should perform a single, well-defined task, and its name should clearly reflect its purpose. Personally, I feel this definition doesn’t fully capture their importance. Over years of experience, I have gradually come to appreciate the true value of using pure functions, as they help maintain data integrity and reduce the risk of unintended consequences when modifying existing code. I believe that updating your code is much simpler when you need to modify only one of the pure functions.

2. Condition must be a constant

One of the challenges when modifying code is not fully understanding its logic. Sometimes, the same logic might be implemented in different places with different names because multiple people are working on related tasks simultaneously. This can lead to a cycle of fixing, testing, and re-fixing issues until you feel that there are no more strange results outputting. This will make your colleagues happy if we can convert important comparison conditions or logical rules into constants that can be reused as needed.

3. Comments and Variable Naming

I used to think that leaving many comments in the code would make it look unprofessional. However, these descriptive comments are invaluable during the maintenance phase, especially in an international environment with engineers from different countries. Engineers may use variable names that are meaningful in their own language, which is why it’s important to include comments next to variables mentioning the terms described in the specifications. Additionally, using consistent variable names for the same concepts across different parts of the code can further enhance clarity and understanding.

Another interesting thing is, if you observe how functions in a library are documented, you’ll notice that they include descriptions of the function’s purpose, inputs, outputs, examples, and other relevant details. We can apply a similar approach to our own code, even if it’s not necessary to write a full description. It’s helpful to leave explanations for any complex logic to make the code easier to understand.

4. Integration tests

Although writing test cases can seem tedious and time-consuming for developers, I must acknowledge their importance. Well-written test cases, especially integration tests that cover interconnected components, can save us time by quickly identifying problems when we inadvertently make changes we shouldn’t have.

5. Code review

Last but not least, the final point I would like to mention is the importance of code review. To evaluate whether your code is easy to maintain and understand, ask others to review it. If they can comprehend your code with little to no explanation from you, then congratulations—your code is well-written and user-friendly.

6. Summary

I firmly believe that the support we provide to others often comes back to benefit us in return. Therefore, let’s strive not only to be skilled developers but also to be supportive colleagues. Consider the challenges others might face and make the maintenance phase a positive experience for everyone!