Things I Learned in the Hard Way in Software

When you write code on your own, either to learn, for university or for a personal project, it is very different from writing code at work. When writing code for a client or for a company, certain guidelines, principles or patterns are usually followed so that the code is clean, error-proof or so that others can contribute to it.

Working with projects at the work level, I have learned certain principles that are not taught in the university nor in courses, rather they are learned when you have the project in front of you and you have to take care of completing the tasks.

I want to summarize some concepts and practices that I learned the hard way while implementing new features, debugging code that I wrote or developing new applications from the bottom-up.

Think for the long term.

When you start working on an application, you have to think that over time this application is going to grow, its modules are going to change, new features are going to be added, some features are going to disappear and some features for which you have to think about what to have. Consider the following principles when writing code: reusability, flexibility, and maintainability.

Reusability: This means that you have to make the modules you create usable in many parts of the code and avoid having to repeat the same statements in your code. This is related to the DRY Principle or Don’t Repeat Yourself, It states that you have to avoid redundancy in your software.

Flexibility: your code has to be able to switch on and off without having to make many changes to your code and be able to be adapted in different parts over time.

Maintainability: It refers to the ability of the code to be modified over time, to improve the flow, make some changes and that it can be adapted in different places making the smallest amount.

SOLID Principles

SOLID principles are well known when working with object-oriented languages. They are a series of rules for writing clean code that also allow you to understand certain design patterns. These are:

S - Single Responsibility Principle (known as SRP): it states that a module should do one thing
O - Open/Closed Principle: A software artifact should be open for extension but closed for modification.
L - Liskov’s Substitution Principle: An entity can be substitute by another without breaking the existing system
I - Interface Segregation Principle: Prevent entities to use things that they don't need.
D - Dependency Inversion Principle: Abstractions should not depend on details. Details should depend on abstractions.

Black Box

This encapsulation principle has to do with data input and output. A module never has to know how another module is composed, this allows it to reduce its complexity.

I was once tasked with working with a React component which made a request to an API. At that time I had the bad practice of writing inside the component line by line how the API call is executed, that is, I declared the fetch statement in the component, what values ​​make up the request and what values ​​it returns. This had been done in multiple other components.

Over time the components got bigger and bigger and more logic was added and there was some that was related to these API calls. Over time this became tedious as I had to make changes to 6 different components.

After a while I started to do some research regarding refactoring the code and came across an interesting article that talked about the Result-Error Pattern, a pattern that simplified async calls. So I made my React component not know how the API calls are made.

Separation of Concerns

This design principle goes hand in hand with the term divide and conquer. An issue refers to a solution to a problem which means keeping the issues separate at the design level. This allows your code to be more flexible, reusable and maintainable. By having a module that does only one thing, you can make the changes you want without having to worry that something unexpected might happen.

Set your dependencies to a specific version

When starting a new project or implementing a feature that requires a dependency, make sure that you are using a specific version of that dependency or have in a range of 2 versions (>= 5, <5.9). So at any moment you would have to reinstall the dependencies. It won't cause trouble like a method was deprecated or the whole library or framework changed.

Do maintenance, at least every 3 months

Give periodic maintenance to your projects. Both the language and the frameworks and libraries are constantly being updated. Some methods are improved, some methods become obsolete or security changes are applied in the worst case, said library is discontinued and when you want to use it it is already obsolete.

Periodically increment minor versions. These updates include minor code changes or enhancements so you can upgrade to a higher version over time.

When you go to update the dependencies do it one by one. I had a situation where I wanted to upgrade from a version 2.5 to 4.6 in which everything exploded, there were many changes in the framework, many methods were deprecated, some changed their parameters, etc.

Summarize

1. Think for the long term. Make sure your code is flexible, reusable and maintainable
2. Don’t repeat yourself
3. Follow the SOLID Principles
4. Divide and Conquer
5. Set your dependencies to a specific version
6. Do maintenance, at least every 3 months

You must be willing to learn new things while transitioning in the software development industry. New things like methodologies, techniques, tools, etc. are learned, which increases our toolbox when we get our hands on a project. It is always good to accept the advice of the most experienced programmers or also see code from other projects. There is always something new that one can learn from others.