Infusion is an open-source tool that is used for generation of documentation in your code files. It uses OpenAI gpt-4 model to write comments. It was my project and I wrote it in Python.
GitHub link:
https://github.com/SychAndrii/infusion
explainer.js is an open-source tool that is used to explain code snippets in your code files. It uses Groq models to write comments. It was a project of my teammate @aamfahim and he wrote it in Node.JS
GitHub link:
https://github.com/aamfahim/explainer.js
I am currently enrolled in an open-source course at Seneca Polytechnic, where we were tasked to team up with another person and review each other's code and give some suggestions for improvement using GitHub issues. I am going to describe this process.
Mode of communication
Most of the issues generated for both repositories were done using synchronous communication via Discord call. After that, we talked asynchronously using Discord messages, since there was a difficult issue for me to streamline setup of my project using bash scripts, and calling my teammate every time I needed to test if it works on his machine seemed unnecessary. Testing using Docker containers and WSL Linux sub system on my machine was not the same as testing them on Al's system, and it highlighted important bugs.
Experience of reviewing someone's code
I did not experience anything unusual when reviewing my teammate's code, since I have lots of experience with Node.JS development. I liked creating issues and then immediately suggesting solutions to them though. One problem we had is that we could not figure out a way to allow me put labels on the issues I created, only Al could do it, which was annoying.
Experience of someone reviewing my code
Al suggested a lot of room for improvement, particularly with installation of my CLI tool. When he first forked my repo, it was a requirement for the end users to go and install a particular version of python manually, which is definitely a frustrating task. Additionally, he highlighted other possible improvements for convenient usage of a tool, like introducing .env file so that you don't have to input your API key every time you start the tool. I like getting input on my code from other people because it allows me to grow as a developer and it definitely expands my view of development lifecycle.
Issues during reviewing and testing
Most of the problems we had were with my tool, because Al's CLI program was written in Node.JS and we both have a lot of experience with it. In contrast, both of us don't like Python ecosystem, so we had a lot of troubles interacting with it. When testing Al's repository, I found the docs written in his README to be misleading or confusing to understand, especially the model and api-key options. We had to go through the process of trials and errors to figure out which API keys and models are accepted by his tool. When it came to testing my repository, version of python on Al's system was very outdated (2.7), so he had to install 3.10.6 (version, required to use my tool) manually. However, even then the problems did not end. Even though he installed it, it was still not being recognized by the virtual environment my tool creates with pipenv. After that, we also had frustration with entering the API key required for the usage of my tool every time we started it. Finally, the README docs did not help with the installation. We tried to follow them, but we kept getting errors related to some scripts not being recognized on the PATH. That's when I decided that we need some sort of automation tool that does all the installation for you. One thought I had is to dockerize the application, but then it would require me to somehow map Docker volumes to the output directory and input files specified for my tool, and that would complicate everything twice. Thus, I remembered that a lot of package managers are actually command line tools, and if you install them by cloning a GitHub repo, then you need to set them up by executing some kind of bash setup script. So that was the idea that I decided to implement. Finally, both of us could not figure out a way to assign labels like bug or enhancement to the issues we filed.
Issues I filed
Issue 1
https://github.com/aamfahim/explainer.js/issues/13
Basic -h flag documentation enhancement.
Issue 2
https://github.com/aamfahim/explainer.js/issues/12
The temperature option did not work properly even if it was within valid range (from 0 to 2). Turns out the CLI framework Al uses parses all the options passed to it as strings, so I suggested converting the temperature to a number before passing it to the API request.
Issue 3
https://github.com/aamfahim/explainer.js/issues/11
My teammate forgot to implement a flag, which was mentioned in a README file as working, which is misleading.
Issue 4
https://github.com/aamfahim/explainer.js/issues/10
This one is pretty interesting. First of all, README does not explain which models are accepted by the Groq. But even the allowed model we tested did not do the job of the CLI tool, since it was classifying the code based on the safe/unsafe evaluation, which is not what we really want for this project. So I suggested narrowing down a list of allowed models to use and update the README to include this information.
Issue 5
https://github.com/aamfahim/explainer.js/issues/9
This issues covers points I have mentioned before. Some flags are misleadingly documented, and some of them are not documented enough.
Issues that were filed on my repo
Issue 1
https://github.com/SychAndrii/infusion/issues/11
The problem was that I confused LLM with my prompt. I told it that I only want source code from it, and at the same time I told it to send the word 'error' if the code it read was not following language's syntax. Additionally, I rephrased my prompt to be more strict with files that do not contain valid code.
Issue 2
https://github.com/SychAndrii/infusion/issues/10
Basic -h flag documentation rewording.
Issue 3
https://github.com/SychAndrii/infusion/issues/9
I also found it annoying to define the API key every time I run the app, don't know how I didn't think of creating .env file.
Issue 4
https://github.com/SychAndrii/infusion/issues/8
I have decided not to go with dockerizing my app, because then it would not really feel like a true CLI app, and instead decided to have shell scripts for setting up all the dependencies and the correct python version.
Issues I managed to fix
I fixed all of my issues. All of them took less than 30 minutes to fix, but there was one issue, that took me like 2-3 hours to fix:
https://github.com/SychAndrii/infusion/issues/8
It might seem weird since enhancement of README file should be easily achievable, but what the first suggestion by Al required me to completely remake the installation process of my tool, which required me to introduce 2 scripts for installation - one for bash and one for Powershell. The problem I could not solve for most of the time was that even though these setup scripts properly installed the needed version of python, this version of python was not passed down to the virtual environment, which you need to enter before using my tool. Eventually, I fixed that though.
What I learned
I have definitely improved my README skills. The way I provided example usage was very confusing for the end user. Additionally, I have finally used bash and powershell languages to do something myself, not for a school assignment, not because it was a requirement, but because I wanted to simplify the process of interacting with my tool. Finally, I decided to face the language I absolutely can't stand - which is python. Working with it was definitely not enjoyable for me, but I think it's essential to be able to use it if you want to find a job today, especially with AI trending.
Top comments (0)