Learning to do a Code Review

For week 2 in my course Topics in Open Source Development, I was tasked with reviewing another student's code, mismathh.

Finding a code review partner

I found mismathh in our course's Slack forums requesting a code review for his project TILerator. I happily agreed, sent him a link to my own project (til-to-html) for review, and checked it out.

TILerator is a command line tool written in Node.js that converts Markdown into static HTML pages. I found the project to be well organized and documented. The code was robust and straightforward to read, arguably moreso than my own. The program was perfectly functional and I did not encounter any functional issues amongst the test cases I could come up with.

Finding issues in my partner's code

I was struggling to find noteworthy issues; I posted 7:

Replacing console.log calls with console.error when reporting errors to the client
Having git ignore output files generated by the program
Upgrading the Markdown parser to handle Markdown links
Cleaning up extraneous whitespace generated in the raw HTML
Not using "#" characters in filenames
Fixing a potential bug where command line arguments were handled slightly differently when run using npm run start vs. invoking node

Resolving issues found in my code

Here are the links to the issues posted on my repository: https://github.com/paulkim26/til-to-html/issues

mismathh submitted 5 issues which I have fixed. He noted:

The help message could be more verbose.
Instructions could provide additional hints/caveats for installing bun on Windows.
A typo.
The <title> tag was not correctly populated in the generated webpage files.

Observations

By testing/reviewing a colleague's code and receiving feedback on my own, I learned:

There are different ways to document and write code - there are generally "good" ways to code but no ultimate one-size-fits-all solution.
It can be frustrating to receive an issue/bug report that doesn't include steps to reproduce said issue.
It is always good to be as verbose as possible in code documentation, even if I don't necessarily need it. I have to understand everyone is starting with zero context of my project.

Thanks for reading!