In my Open Source Development class, my class has been tasked with implementing their own command-line tool that converts Markdown files (as .txt files) to HTML files, and is to be used to help users author "Today I Learned" (TIL) posts. Students are allowed to use any language they want, so I decided to write the tool in C++. I have a fondness for C++ as it was the first programming language I studied seriously in class. My project, ctil (Today I Learned in C++), can be found below:
https://github.com/rjwignar/ctil
Lab Exercise
Part of this project is a lab exercise that involves students reviewing and having their codebases reviewed. The class has a Slack group that helped students partner up for this lab exercise. Because of this students were easily able to find partners, either by replying to channel posts or making their own.
Reviewing Code
For this exercise, I reviewed BukuRain by pbelokon:
https://github.com/pbelokon/BukuRain
I haven't taken much time to review the code itself, but after installing and testing I found that the project fulfills most if not all of the requirements. I did post a couple issues to the project, both of which suggested updating instructions on the README file. For example, I had trouble installing BukuRain by following the original instructions, which suggested running npm i. After consulting pbelokon, I was suggested to run npm i -g (global installation), and I could then run the program without issues. Additionally, I suggested updating the ReadMe with usage examples. BukuRain has a flag for specifying an input file/folder, -i, and -o for specifying a destination folder for the output.
I suggested that users could benefit from having usage examples of these flags on the README file.
The issues I posted can be found below:
Reviewing BukuRain was a fun exercise in reviewing code. Although I did not review the codebase thoroughly enough to identify any bugs, I was able to suggest improvements to the README that would allow future users to use BukuRain immediately without issue. This exercise helped teach me that descriptive documentation is just as important as having a robust and functioning program, a lesson I would learn again when my project was reviewed.
Getting your own code reviewed
My lab partner suggested two changes to my project. Previously, I mentioned the importance of descriptive documentation. The first issue raised suggested I update my README with installation instructions and execution samples. The second issue raised was a proposed bugfix to my code to allow my program to work with text files with a period . in their name before the .txt extension (filenames such as example.file.txt).
The issues raised for my project are available below:
One of the consequences of writing an Open Source project is that the project is exposed for others to review and critique. Opening your work and by extension, yourself, to criticism can be tough and takes a lot of courage. However, I understand it is required to improve the project and ultimately improve as a software developer. When I found a partner for this lab, my implementation was mostly incomplete, so I was a little anxious about sharing my codebase.
Both suggestions made to my project were helpful and greatly appreciated. Due to the raised issues, I was able to work towards a more descriptive README file, and I learned of a bug I may not have spotted otherwise. Though my project is still incomplete, I was able to implement these suggestions and fix my issues.
Lessons from Reviewing Code
Though I did this exercise with a classmate, I learned lessons that also apply to the Open Source community.
From testing and reviewing code, I learned the importance of descriptive documentation. Both my partner and I found ways to update the README files for our projects to become more helpful for future users. From this experience I was also reminded how classmates, coworkers, and the Open Source community can always help spot bugs or errors you may not notice yourself. When making an Open Source project, it is important to leverage the Open Source community for feedback and improvements.
Top comments (0)