Last week, I reopened a JavaScript Code Repository that I first authored two years back. The nature of some of my work requires that once mission accomplished, I move on to a task maybe of entirely different nature and level of coding.
In such work scenarios, I only come back to the repository when one of the following happens:
- Bugs or Performance Bottlenecks that are clearly a hindrance for successful operations
- Feature Requirements
Many times, especially after long intervals of writing code, I have the urge of diving right into the codebase and start cranking new code. This was one of those times when I was just too excited to listen to *tap* **tap* of my ThinkPad T480.
Hacktoberfest Plug
Btw, by the topic of code, fixing bugs and adding features. I just remembered that Hacktoberfest has already begun. I am very excited to participate in this year's Hacktoberfest starting with this PR merged soon in the ever awesome and generous Aaron Abramov's testing library, k9 for rust. 3 left to go after this one. Maybe one of those PRs you and I make would delete some of the same unused to avoid same kinds of mess up, which is the topic of this discussion, its all tracked by Git after all, so no problem deleting right?
Continuing to my story. So, A couple of Pomodoro Timers and writing a bunch of code I think was a good start. To my surprise, much of the logic I was wasting time on now was already well integrated. Which meant the pomodoro timers were as good as spoilt pomodoros.
On some post messup investigation, It seemed that at some early point I rewrote the logic into a submodule but never thought to delete the initial files that contributed to the good ol' spaghetti. At this point, I made some more fixes after going through the code and added a bunch of features. While being repentant to delete the files at the spot if they're not being imported anymore.
It wasn't all doom though, I was nowhere near the progress of the code I wrote at my previous stint at this module. Plus, it also came with fixes and stability worth of an year's time. But, considering I was the original author of the project. I can't help but imagine anyone else falling for the same dilemma with more intensity and frustation if they don't go through the entire codebase line-by-line. To add to this failure, there was no documentation at the time.
So, Here's one of the most prominent Unknown Unknowns of this repository. This term comes from the book Philosophy of Software Design which I am currently still reading. Courtesy of the book Issuance department of a local library. The unnecessary commented code and unused files certainly create obscurity and confusion for someone. Hence, this is a mistake not worth repeating ever again.
Action Items
So here are some actionable items and pseudo code of what I will be doing, when authoring my future code.
- Unused Code should be removed or its purpose clearly commented
- Unused Files should be removed or any purpose for which it exists should be clearly commented
- Preferably delete them and Commit to Git
- Maintain a CHANGELOG.md for all the previous changes along with the commits
- Make this CHANGELOG.md easily discoverable
- Document the entrypoints of the code in README file
For all the authored in the same manner in the past though, I will take some time to ensure that unused codes is not there anymore whenever I find a chance to reopen those. Future maintainers, I will make you proud, I promise.
Bonus Content
This reminds me of an event in around 2014 - 2015 time, when I was participating in Google CodeIn and I was politely scolded by one of my kind mentors from India 🇮🇳 for leaving commented code within the Pull Request I created to the project.
Although, I don't make the mistake of having commented code anymore. The deeper meaning or philosophy there was to not have useless and meaningless things in code and keep the codebase Clean. At the time I am afraid I missed it. But about 7 years, I am finally here repenting and vow to not make this mistake.
Thank you!
Thank you for reading my blog post and visiting my blog. ❤️
I appreciate your time and would like to learn from your experiences of writing code. You can share them with me @computistic on Twitter or email me at [email protected].
Stay Well Slept 💤💤💤