This is a guest blog post by Claudio Pinkus, co-founder of CodeStream
According to the 2018 Stack Overflow developer survey, less than 20% of developers report using internal documentation when trying to address coding issues at work. In fact, some report spending as much as 75% of their time trying to understand the code they inherited, which is often poorly documented. Providing a mechanism to document code without requiring developers to change their workflow or habits can lead to a significant reduction in onboarding time, while simultaneously improving code quality.
CodeStream is an IDE plugin that allows you and your team to discuss, review and understand code. It connects information contained in team chat conversations, issue tickets, pull request comments, and other metadata to the code snippets they refer to, thereby producing documentation in context, automatically, within your IDE.
Taking Over an Existing Codebase
When working on a new project, developers inevitably have a ton of questions. Getting answers is often harder than you might think, as it usually involves copying and pasting code snippets into Slack or Microsoft Teams, where you have to recreate the context you just lost by leaving your IDE.
This is why we built CodeStream. We believe that asking questions about your code should be super simple, and if we can make it so, it will happen more often. As questions are answered faster, problems are averted. The questions (along with the answers) must be linked to the code block they refer to, so that they become documentation, which will be visible and available in context. CodeStream reduces the 18 steps to just two:
1) Select the code block.
2) Ask your question.
Note that the referenced code block is highlighted while the cursor hovers over the conversation. The conversation that leads to the answer can take place in Slack, within CodeStream’s embedded messaging, over email, or (soon) Microsoft Teams. It must originate in your IDE if it is to be linked to the code itself. Once the discussion has a resolution and an answer has been arrived at, you can “star” that reply so that only the Q&A pair is visible next to the code block in question, similar to Stack Overflow’s accepted answer.
CodeStream is designed for teams, but not everyone needs to be working in their IDE to participate in the conversation. If you are in Slack, for instance, the conversation will be presented with the appropriate context automatically, and when you reply to the thread, the reply will automatically show up in CodeStream, next to your code, exactly where it belongs.
The Knowledge Base Behind Your CodeBase
Every interaction in CodeStream is automatically added to a knowledge base. Because every entry is linked to the code it refers to, upon clicking on it, it opens the right file and highlights the right code block for context. If you are trying to understand the code you’re looking at, CodeStream will guide you through the conversations that will often explain how and why it works the way it does. By providing this knowledge to your whole team, CodeStream accelerates your learning, reduces repetitive questions, and improves the quality of your code.
Create Issue Tracking Tickets in Your IDE
CodeStream also allows you to create tickets in your favorite issue tracker directly from your JetBrains IDE. Select the code that contains the issue, and click on the “bug” icon to create a ticket.
Next, select the issue tracker you want to use and authenticate. CodeStream currently supports many popular issue trackers, including YouTrack by JetBrains. Enter a description of the issue, assign it to someone if you wish, and CodeStream will create a ticket that contains all of the necessary context for the assignee to understand exactly what to fix. Best of all, the ticket will be linked to the code, and the code will be linked to the ticket – so now whether you’re looking in your issue tracker, or at the code itself, you’ll see that issue in context.
Continuous Code Review improves Quality
As you make changes to existing code, you may want to check with your teammates to make sure your approach is the right one. CodeStream will allow you to share code even if it is saved and collaborate with your team before you commit it. Your teammate will receive your question or suggestion, and can easily compare your proposed code with that in their version. This will even work if the comparison is on a different branch, or the code block has been modified locally.
After reviewing the delta, if they agree with the approach, they can just apply the patch and set the correct course before a commit and without a pull request. This improves code quality because it addresses potential problems at coding time rather than waiting days when the course will have been set, and technical debt may have accrued before it is possible to do a formal code review.
Bringing it All Together
CodeStream connects information about your code that lives in the tools you already use, such as team messaging, issue tickets, training materials, and soon, pull request comments, and links them to the code blocks they refer to and produces a knowledge base that explains how your codebase works. As a result, it helps shorten the onboarding of new devs, improves code quality, and protects and retains vital company knowledge. Click here for a 2-minute demo of CodeStream in action.