This week, I almost finished working for the 0.1 release of my TIL, i.e. 'Today I Learned' post generator tool. The entire process was not only coding and documenting, but also included collaborating with fellow peers, asking for review of your work, and reveiwing theirs.
The process was part of the training to prepare us become comfortable with the practices that are common when trying to work on Open Source Projects.
In this post, I will try my best to share my experience being part of this process, and how it helped me improve my project after I thought I was done ("Software is never done").
Finding a partner 👨💻
As hard as this part sounds, trust me, it wasn't. Finding a partner to collaborate with was as simple as dropping a post on our course's slack channel:
And in a few minutes, I got a reply from a person who was willing to review my repo, and we took it from there.
Reviewing my partner's code 👁️🗨️
The goal of this process was to review your peer's code, documentation, and program behavior, and to open any problems found as GitHub issues.
To begin with, I started looking at the README file, that was supposed to provide description of what the tool does, installing the dependencies, and how to use its various features. Within first few seconds of my read, I found a few formatting errors and typos, for which I opened the very firsts issue.
Just like that, I continued examining the code, installing the dependencies, testing supported functionalities as per the documentation, and quickly identified several issues in just 10 minutes. Therefore, the entire process went as smoothly as jelly 🍮.
Getting my code reviewed 👁️🗨️
As expected, getting my code reviewed was a really fruitful process. My fellow classmate was well-detailed in his approach to review my work, and opened 5 issues in my repository that I would have easily missed even after a second self-review.
Types of issues
All the issues were meaningful and fixing them would add some actual value to my project.
Some of the issues complained about lack of detail in my documentation, some talked about how a certain part could be done in a more elegant manner, and one issue (surprisingly 😲) found a bug in the major functionality of the program.
The problem was whenever the command was given a single file, it would not generate anything, even though everything worked well in case of a folder. This issue, in particular, was highly valuable as I was never (sub-conciously) planning to check my tool against a single file. My thought process was if it works for a folder, it should definitely work for a file. Turns out, I was wrong!
All in all, there was just one of them I didn't find to be an issue, but I am still waiting for follow up from my friend.
Follow this link for more info:
https://github.com/Amnish04/til-page-builder/issues/5
Issues I found ❗
I found around 6 issues when looking at my partner's repo. Here's a list of all:
- Formatting issues in Readme.md
- Missing requirements.txt - something similar to package.json in Node.js
- Invalid Dependency documented in README
- The program wrongly identifying a provided text file as unsupported
- Extra newline at the top of every generated HTML file
- Improperly indented HTML files
Issues found for my work ❗
Around 5 issues were opened for my work, and they are as follows:
- Missing README documentation
- Generation of empty paragraph tags
- Program not working when single file provided
- Recommnedation for code simplicity
- Issue with output option when defauat value provided
Fixing my issues 😎
Fortunately, I was able to fix all of my issues quickly as I already had an idea where I might have gone wrong.
Other than that, since the detailed issue descriptions also proved to be helpful as some of them contained hints that led to fixing the issue.
Splendid times!
Learning 📚
The biggest learning I had from this process was, as I mentioned in the beginning as well,
Software is never done.
No matter how hard you try to build a flawless software, there will always be issues or room for improvement. Having additional pairs of eyes always helps in detection of issues you might intentionally/unintentionally turn a blind eye to. And that is what serves as the Foundation for High Quality Software.
Top comments (0)