GitSlash

De-couple comments from your code so that you can1. narrate the story behind your code with detailed comments2. manage code comments without touching source file3. ship lighter code

Comment

Inspiration

I still remember the very first merge that I made to a production code line. It was a minor enhancement. As part of the code changes, I also included comments explaining the logic. A lot of comments. Around 10 lines of comments describing the 5 lines of code changes. Our team did not have any standards for writing comments and this passed the code review. This became a habit and I would write long descriptive novellas for every code change that I was making. This was appreciated by the maintenance teams, who found it very easy to understand my code and helped them diagnose bugs much faster.

However, a problem crept in. Our code files started getting large. The storage space requirements started increasing and even working with these files in IDEs became a hassle, especially working with files that were hosted in VMs in other countries. Loading times increased, scrolling and navigating the files was starting to become a pain. So, I had to cut down on the habit of writing detailed comments.

So there were two needs that were seemingly working against each other:

  1. the need to write detailed contextual comments for code so that it becomes easier for team members (and even for future me :) ), to understand what the code is doing.
  2. the need to keep the code base as light as possible.

Through GitSlash, I am giving developers a way to meet both of these needs, without having to compromise on either.

What it does

GitSlash is a platform that allows you to add contextual comments to your code, without the comments being added to your actual code file. Instead, the comments, along with a reference to the point in the code file are saved in a separate repository. This allows developers to write detailed comments to their code, without affecting the size of the actual code file.

Some additional benefits include:

  1. Since the comments are not in the actual code file, developers can keep adding/editing comments without having to put the code file through a CI/CD process. Today, even to make a small correction in a typo in a comment, you would need to do a whole release cycle.

  2. A new way to search code. By searching a repository of detailed code comments, instead of the actual code, developers can now search by the functional description of what the code does, rather than by actual code lines. This is super useful as codebases start getting old and the teams maintaining the codebases don't really know where things are.

  3. This also allows developers to find repeatable solutions to problems that other teams have already built (a common problem in large distributed organisations with multi-product portfolios). For instance, if I want to create a function in Java that performs a complex data type transformation, before building it from scratch, I can search my codebase to find out if other teams have already built something similar and then resuse/extend that. Similarly, teams can avoid rebuilding entire product modules (unbelievable as this sounds, this is a common problem in large organisations such as Amazon, Oracle, Microsoft, Google etc., where there are too many teams building too many products.

How we built it

GitSlash was built and hosted on an instance of the Oracle Autonomous Database. The backend is completely in PL/SQL. The front end was built on the Oracle APEX framework.

Challenges we ran into

I'm not quite the expert when it comes to front-end development. Some UI elements of GitSlash were quite complicated for me; such as selecting a segment of the code, and adding a comment on top of that in a single page, without too many clicks.

I'm sure a solid JavaScript wiz could improve these capabilities quite easily.

Accomplishments that we're proud of

  1. During my stint as a developer, this was a problem that I had faced myself. Building a practical solution to a problem that I faced felt quite cool.
    1. Finding solutions to solve most of the front-end challenges that I mentioned above. Huge thanks to the StackOverflow community and MDN Webdocs from Mozilla.

What we learned

About GitLab - the product and the company. I was not aware that there was a solid open-source alternative to GitHub - run by an interesting organisation.

What's next for GitSlash

I have recently taken a break from my work to pursue my passion for building products. I'm absolutely chuffed about what has been achieved in the past few weeks and I would love to continue building on this full-time.

Immediate areas of focus would be:

  1. Tech re-architecture. Re-build GitSlash in a framework + cloud service that is most compatible with GitLab and is more familiar to the developer community.
  2. In terms of the feature roadmap, I want to keep the core focus of the solution quite narrowed down to comment management (it's a huge space in itself). However, the points of interaction with the system need to be increased. This includes adding items such as
    1. UI components that allow developers to add and view GitSlash comments from within GitLab
    2. Plugins in VSCode and other IDEs to select code segments and add comments directly from the IDE and push to GitSlash, and also view comments within the IDE.
    3. CLI commands to replicate the GitLab repo structure in GitSlash
    4. The primary reason for writing comments is for teams to read it later. Need to expand capabilities on the search and retrieve capabilities that can be built on top of the stand-alone comment repository.

Built With

Share this project:

Updates