Refactoring code, git rebase, squash, solving merge conflicts, and beyond

Commit

Commit can be found here: ab3f7275

Refactoring Code

Refactoring code is very important for a healthy codebase. As the project grows in size, the quality of the code degrades if refactoring is not performed from time to time which is referred to as technical debt. I performed a lot of refactoring this week to my project. The refactoring tasks I performed are detailed below:

• Extracted at least 3 functions which were made for code reusability since the same code was being used at more than 2 places.
• Improving names of the variables and/or functions and following naming conventions to improve code readability. I believe that there is less need to document the code if the variables and functions are named properly.
• Removed unwanted code. I had a piece of code which after reading the file content, would split the content into an array of sentences and <br> tags for empty lines and then later on I'd replace the <br> tags with empty strings in the array before the content can be converted into HTML tags. The original array that was passed into the function already followed the latter format (an array consisting of sentences and empty strings). So I got rid of the redundant code after I realized how useless the original piece of code that I wrote was.
• Improved code visibility by structuring the comments and code properly. There were instances where some code didn't follow the conventions that were set by myself. These had to do with comments where they were either missing some context of what the code does or had extra spaces beneath itself which might bring ambiguity for someone who's reading the code to understand a particular comment relates to which piece of code.
• Added code splitting for better code readability and understandability. There were quite a few functions which dealt with generating HTML content. So it made sense to put them into another file that specifically dealt with generating HTML titled htmlGenerator.js.
• Fixed a bug. I found a bug while refactoring the code. The bug was when reading a JSON file using Node.js' readFile() function, I passed a callback function to handle errors. After reading the file, the execution got stuck every time I ran the code and no output was shown on the console. After a lot of debugging, I figured that it was better to use the upgraded version of readFile() i.e., readFileSync() and it can be wrapped in a try...catch block to handle errors when reading contents from a file.

Problems Faced

I started working on refactoring (Lab 5) before another contributor's code was supposed to be merged into the master branch (Lab 4). Midway through refactoring the code I had a PR raised for a feature and had to get it approved and merged to upstream. I knew that was going to cause conflicts because the contributor touched the code that I had changed as part of the refactoring branch it was some commits behind the latest commit on master. Either I merge the refactored code later once refactoring is entirely done and deal with conflicts then or deal with conflicts midway while there is some more work left to be done for refactoring, it was the same story at the end of the day. So I decided to merge the latest code then and there. I was 3-4 commits into the refactoring feature branch when I performed a git merge from the upstream master and boom merge conflicts!!! I was a little bit terrified to solve the conflicts because I've always linked merge conflicts with "I'll lose my code after resolving the merge conflicts!!!", but as I read the code and understood what was supposed to be accepted and what to be discarded, I safely got the changes merged into the latest commit on refactor branch. I faced the same merge conflicts when I was rebasing and squashing the commits because there were a few commits that didn't have the latest code without conflicts from the master branch since I merged the latest code into 3rd or 4th commit on the refactor branch. I sort of panicked for a bit again since I was a newbie to rebasing and squashing. However, I was able to get those changes in as I read the command line instructions to get an idea of how to proceed with rebase and squash.

Git Usage

This was a brand new experience for me of committing small increments of code on the same feature branch multiple times and then rebasing and squashing all the commits into the latest commit to get them merged with the master branch. It was fun to dive deeper into git to learn advanced git usage with this exercise.

Learning Outcomes

I learnt the importance of refactoring with this exercise. Besides, I also got to dive deeper into git which was quite daunting at first but repetition helped me overcome that.