DEV Community: Claudio Pinkus

VS Code, GitHub, and CodeStream: Choosing the best of all worlds

Claudio Pinkus — Wed, 13 Jan 2021 17:37:13 +0000

There is consensus among the thousands of developers we have surveyed that context switching is detrimental to productivity and staying in the zone. One way to reduce this is to integrate the essential tools developers use every day into their IDE. According to the latest Stack Overflow survey, the tools developers use most are GitHub, Jira, and Slack. In this post we will focus on the GitHub integration in Visual Studio Code.

GitHub has been integrated into VS Code for some time now, with versions released prior to Microsoft’s acquisition. The GitHub Pull Requests and Issues extension, now under Microsoft’s ownership, has been downloaded about 1.2 million times and has received an average of 3 stars in the Visual Studio Code Marketplace. Many of the recent reviews are 1 star, as GitHub decided to discontinue its support for GitHub Enterprise. In addition, many reviews state that the extension is very buggy, or just does not work.

If you are interested in integrating GitHub in your IDE, CodeStream offers a better alternative. The CodeStream extension for VS Code supports GitHub Cloud and Enterprise, as well as GitHub issues. If you are not a VS Code user, the CodeStream extension for JetBrains is also available with the exact same functionality. The CodeStream extensions have been downloaded about 300,000 times and have an average rating of 4.4 stars. Many reviews praise the functionality and quality of the extension declaring that it works well and is a great tool for code reviews.

If you are one of those GitHub users who prefers an issue tracker from someone other than GitHub, CodeStream lets you integrate with any of 15 different trackers including Jira, Asana, Trello, Azure DevOps, Linear, and Clubhouse.

In addition to integrating with code hosts (CodeStream also supports GitLab and Bitbucket, but not yet for Pull/Merge Requests) and issue trackers, CodeStream includes a built-in code chat solution that enables frictionless code discussion and integrates with Slack and Microsoft Teams. CodeStream also allows you to request feedback on unreviewed commits without the need for a pull request with just two clicks.

The table below summarizes the comparison between the Microsoft GitHub extension and the CodeStream extension for Github.

Both the CodeStream and the Microsoft Github extensions are free to use for an unlimited number of users indefinitely. If your organization is very security conscious when it comes to code, CodeStream also offers an on-premises version available for a free trial, as shown here. The paid version also includes premium support and reporting features.

JetBrains Space vs. CodeStream

Claudio Pinkus — Thu, 07 Jan 2021 16:12:58 +0000

In December, JetBrains announced general availability of Space, an all-in-one solution that aims to replace an array of tools for the whole organization, from Slack to GitHub, Jira to CircleCI, and everything in between. It’s an ambitious project reminiscent of discontinued integrated environments that faded over time, such as Lotus Symphony – I know, I am dating myself – as single-purpose tools such as Word and Excel emerged as the preferred solution for knowledge workers.

The Microsoft Office Suite (a collection of single-purpose tools) never evolved into a single integrated environment and went on to dominate the office space. Google took a similar approach to the Google Suite. In software development, the most widely used tools today are VS Code (Microsoft), GitHub (Microsoft), Jira (Atlassian), and Slack (soon, Salesforce), as reported in the 2020 Stack Overflow survey. Still, many other companies have significant market share in their niche. JetBrains is well-entrenched as a provider of text editors or IDEs. GitLab offers a powerful code host along with DevOps tools. CircleCI is a market leader in Continuous Integration. And the list goes on. Even the mighty Microsoft has not been able to own every segment of the software development lifecycle, though it keeps trying.

According to a post in Techcrunch, the ultimate goal for Space is to provide a unified company-wide platform expanded to a wider range of creative teams, including designers, marketers, sales, accounting, and more. Seems like a tall order. The problem JetBrains is trying to address is that the array of tools “...leaves people switching tools and tabs, manually copying information, and generally losing time and creative flow” according to CEO Maxim Shafirov. At CodeStream we share his view that it’s a big problem development teams need to address, but our solution is quite different.

First, we are focused exclusively on developers, because they are drastically underserved when it comes to integrated solutions, and in particular, have unique needs when it comes to communication tools that are code aware. This point is fundamental when it comes to reducing context switching. Second, we aim to deliver a seamless solution by integrating the tools developers already use into the IDE of their choice, rather than adding yet another separate app into the mix. CodeStream supports 14 different IDEs, including all of JetBrains’ and Microsoft’s. It integrates with over a dozen issue trackers from Asana to Jira, to Azure DevOps, six code hosts including GitHub and GitLab, both cloud and on-prem, Slack, Microsoft Teams, and e-mail.

Here is a table that summarizes the main differences between JetBrains Space and CodeStream:

If you envision moving all of your collaboration to a single app that replaces your existing tools and workflows, then JetBrains Space looks like a good solution. If you would rather find a way to reduce context-switching, improve collaboration and boost productivity while still retaining the tools and workflows you are currently using, then CodeStream might be right for you.

Fixing a broken software development process through better technology

Claudio Pinkus — Wed, 04 Nov 2020 21:21:41 +0000

Introduction

The software development process keeps evolving to keep up with the demands of the enterprise. As software is (famously) eating the world, more and more organizations make more software, have more frequent changes, requirements and integrations, and must manage a global workforce of developers. Software is now discussed in boardrooms as a strategic asset that drives value creation. In addition, work-from-home is the norm, at least for now, and the trend might stick for the foreseeable future. All this is straining the traditional approach to managing software projects. The assumption that a small team, co-located in an office, can easily communicate, plan and execute is no longer valid. A new approach is needed.

A collaboration gap

The typical planning process for software development teams is structured around a sprint. It starts with (a) the allocation of tasks, followed by (b) the execution of those tasks, such as developing a feature, and it ends with a (c) code review triggered by a pull request. During phase (b), developers typically don’t collaborate much. By the time a code review begins, often after a week or two of coding, the amount of work required to rework a suboptimal solution often leads to compromises and the accumulation of technical debt.

The code review process, which typically involves the developer and one or more reviewers, is also meant to share knowledge about the codebase. While ephemeral knowledge is exchanged among the immediate participants, that knowledge is not captured in a digestible form and is not widely available to other developers in the organization. That leads to a knowledge gap that manifests itself clearly when key developers leave the organization.

While developers spend most of their time in the Integrated Development Environment or IDE, IDEs have until now not served as collaborative tools and do not include the essential communication, project management and knowledge sharing components that reduce collaborative friction. Therefore, developers must jump from their IDE, to Slack, to Jira, to GitHub.com, to email, many many times per hour, in order to collaborate. This context switching is highly inefficient, disruptive, and going forward, unnecessary.

Shifting Left in Developer Collaboration

In the last decade, the Shift Left Principle has taken over the software operations and quality assurance process under the newly coined term DevOps. As defined by AWS “DevOps is the combination of cultural philosophies, practices, and tools that increases an organization’s ability to deliver applications and services at high velocity: evolving and improving products at a faster pace than organizations using traditional software development and infrastructure management processes.”

Still, the “Dev” half of the DevOps equation remains less automated, less collaborative and less efficient than the “Ops” side. According to Devopedia “The principle of Shift Left is to take a task that's traditionally done at a later stage of the process and perform that task at earlier stages.” The answer we are looking for in addressing the deficiencies in developer collaboration might be a combination of shifting left from a cultural perspective while adopting practices and tools that integrate the essential tools into a collaborative environment.

The IDE becomes the Hub

While the software development process has always involved many participants, the IDE has generally been seen as a standalone, single player tool. In order to stay in the zone, developers shunned distractions, and the IDE was intentionally kept isolated from the communication and collaboration aspects of the software development workflow.

GitHub, Jira and Slack are the most widely used tools among developers, according to the 2020 Stack Overflow Survey. All three are part of the collaboration required to produce high quality software on time. But none of them were integrated with the IDE as a natural environment when code is written and all appears in context. GitHub is mostly used in a web browser, causing regular context switches between the IDE, the command line and back to the browser. Collaborating in Slack requires developers to copy and paste code, a tedious and infrequent task, and then to explain to the recipient the context that was just lost through the cut and paste operation. Over the last 20+ years we've seen incredible innovation in the browser, as web technologies make it easier to deliver robust and compelling user experiences. So perhaps it's no surprise that Jira, Github, and Slack are all web-based.

Starting with the Atom editor 6 years ago, and more recently popularized by VS Code, editors can now be extended with web technologies. This opens up the possibility of bringing these powerful capabilities directly into the IDE. Since context switching represents 70% of the steps involved in the unintegrated developer workflow, the same work can be accomplished with ⅓ the effort in an integrated environment where pull requests, issue tickets and messages are associated with the code itself.

From Transparency to Visibility

Many organizations are striving for transparency as a matter of cultural adaptation. When transparency is implemented, better alignment is possible. Communication becomes more streamlined and overlapping departmental and personal responsibilities are better clarified and defined. In order to become more transparent organizations must deploy technologies that increase visibility.

Examples abound: Many teams share calendars in order to coordinate schedules and meetings, many of us set our status on Slack or Microsoft Teams to show our availability, and in this year of Working From Home many have chosen to keep a Zoom call open among team members to be able to casually discuss ad hoc issues. Still, software developers keep working away in their IDEs after grabbing a ticket and emerge from their focused sprint with an almost finished product. If the individual IDEs were connected to each other in a team setting, increased visibility could be possible. Team members could see what the others are working on, team leaders could help out someone who is blocked, and software quality would improve on the first pass.

A New Workflow is Desirable

It is both possible and desirable to integrate the essential tools developers use every day in order to boost collaboration, timely communication and reduce errors and technical debt. The technology is available. The most important step now is to redefine what’s acceptable from a cultural perspective so that developers can feel free to share imperfect work early that is made dramatically better by the contributions of their peers, thus fostering shared knowledge.

We must step forward in the direction of a new modern workflow where integrations are the norm, code reviews happen sooner and more often, and knowledge is shared effortlessly through technology.

All Remote: Documenting your code is now essential. There is a better way. (Part 4)

Claudio Pinkus — Wed, 20 May 2020 14:48:36 +0000

Introduction

In Part 1, we discussed the personal and human factors affecting all of us during the COVID-19 pandemic. In Part 2 of this series we talked about how a combination of cultural and technology factors has traditionally led to insufficient collaboration among developers. In Part 3 we discussed how transparency needs to turn into visibility in order to create team alignment and boost velocity and productivity. We turn now to documentation as a tool to improve remote developer performance.

Documentation has been a source of frustration and conflict in software development for many years. The problem is, fundamentally, that many developers don’t document their code, or do so poorly. As a result, other developers who need to understand the code they are utilizing or changing spend many frustrating hours addressing this shortcoming. Understanding code can take as much as 10X the amount of time as writing new code.

Why don’t developers document their code?

There are many examples of articles and posts that discuss this question. For instance, this article in Infoworld from 2012 asks “Why don't programmers document? Real programmers don't document is an old chestnut of hacker machismo, one that some coders have sadly taken to heart,” Infoworld states. Their answer might reflect a nugget of truth, but is by no means a universal explanation nor a solution. In a post in 2018 Tomer Ben Rachel argues that “The main reason code goes undocumented is because of time. When developing a feature that needs to be completed within a certain time frame, rarely do we have a moment to stop everything and focus on documenting our code.”

In an all-remote world, documentation is one more essential tool to sustain team alignment. This is a great moment to revisit how we think of documentation and its value. The good news is that there is a better way.

The dawn of On-Demand documentation

At CodeStream we have been working to improve internal documentation practices for over two years. Given that so many fast-moving organizations don’t produce much useful documentation, and that surveys show that less than 15% of developers use internally generated documentation in their work, we believe in on-demand documentation. What does this mean?

When a developer implements a new component or module, instead of trying to figure out in advance what others may not understand when they encounter the code in the future, CodeStream allows the developers using that code to more easily ask questions, and pull the information from the authors. We have implemented an in-editor interactive FAQ approach that captures the question and answer interaction and attaches it to the code it refers to. So not only do the missing pieces get filled in to solve the immediate need, the discussion is saved alongside the code for the benefit of the next developer who consumes the component or module.

Bringing it back to the IDE

Until now, information about your code that explains how it all works has been fragmented, spread out in a variety of different tools and systems. Finding the right information is quite time-consuming, and sometimes impossible. By tying it all back to the IDE and, specifically the code it refers to, documentation emerges as the byproduct of the interactions that take place every day among developers in Slack, Jira, GitHub and other systems. CodeStream inserts itself in the workflow to capture and organize the information so that it becomes accessible and actionable in your editor. Given that the Number 1 Challenge for developers today is sharing knowledge, CodeStream sits exactly where the intersection of documentation and collaboration lies. Collaboration solutions that are specifically designed for developers will become the foundation of useful on-demand documentation.

The future of documentation in On-Demand

The future of software development will include a higher percentage of remote co-workers and teams. We have seen that an all-remote approach requires flexibility, the right collaboration tools, transparency and visibility. It also requires a new approach to documentation if we are to make all-remote work as effective as sitting side by side in an office. Adopting an on-demand approach to documentation solves two problems we have been wrestling with for a long time. It relieves developers from investing time and effort trying to figure out what others might not understand, and it improves knowledge sharing not just among two developers but for the organization as a whole.

All Remote: Transparency becomes essential when working all-remote (Part 3)

Claudio Pinkus — Wed, 20 May 2020 14:41:16 +0000

Introduction

From a technology perspective, until recently it’s been surprisingly difficult to carry out simple tasks like asking a question about code you are viewing in your editor, but don’t understand. If you are among the developers who use tools like Slack or GitHub to discuss code, there are some significant limitations in both, but for different reasons. Developers often turn to Slack to ask ephemeral questions about code that’s unclear, but this involves copying and pasting from your IDE into a channel, and having to then recreate the whole context you just lost in order to explain to the recipient what they are actually looking at. Code reviews are often conducted In GitHub, where the context is more clear, however, you are limited to discussing only the changes that are part of that PR. What if you have questions or a suggestion about another part of the code that is not changing?

Here we will focus on another aspect of remote work. Before your team went all-remote, it was relatively easy to keep informal tabs on what everyone was working on. Just looking around you, could see who is at their desk or in a meeting, or who moved a task on a board. Gone is the physical tap on the shoulder to ask a question or bounce off an idea. In an all-remote world, there is a need to become more transparent in order to improve collaboration, perhaps to demonstrate to your boss that you are actually working while at home, and most importantly, to improve performance and code quality for your team and your company.

What is transparency in software development?

One way to think of transparency is to consider it a philosophy, or a point of view. It implies openness, communication, and accountability. Transparency is operating in such a way that it is easy for others to see what actions are performed, and how they are performed. The benefits of transparency were well understood long ago. As explained by Nathan Donaldson of Boost, there are many different dimensions to transparency. For a manager, it might mean knowing the status of a project. For a developer it might be seeing work in progress on a board. In both cases, it’s about producing the best product with the lowest risk. This chart from Boost, who specialize in Agile risk management, illustrates its benefits:

From Transparency to Visibility

Kanban-style boards have been popular in software development for a long time. If you used to rely on a physical board to have visibility of the state of a project, in a remote team that becomes impractical. Some software tools, like Trello, implement the methodology of a kanban board and give you task level visibility of what your teammates are working on. That is very useful and quite adequate for improving visibility in a remote team. However, the value of radical transparency becomes more evident in a remote environment. As communication is a bit harder, it’s easier to make mistakes or incorrect assumptions.

As described by Matthew Bellows in this post by First Round Review, there is a strong case to be made for Radical Transparency among startups, which is likely to apply to companies of all sizes. Matthew says: “Whether you’re starting from scratch or looking to make your existing culture more transparent, start by building it into the tools you use every day. Make the executive team’s calendars visible internally, for example, so everyone can see who’s in a given meeting or when colleagues are available.”

That is why at CodeStream we have been working on giving development teams the tools they need to increase visibility at a granular level.

The networked IDE comes of age in a remote era

Developers tend to choose their IDEs individually in a BYOD world. In any given team you might find some using VS Code, others IntelliJ, a third group Atom or pycharm. One of the best ways to increase granular visibility is to connect your teammates’ IDEs to each other. That is exactly what we have done at CodeStream. We just introduced Live View, a new feature in our collaboration platform that allows admins or any developer to see a live snapshot of what everyone is working on. Specifically we show each user’s name with a list of the repositories in which they have made local changes (i.e., edits that haven’t been pushed). When you hover over a repo entry, you can see the actual files that have changed, as well as the number of additions and deletions, like this:

Note also the warning sign indicating that Peter may have a potential merge conflict in the “gore” repo. He can then contact whoever is also working on that file in “gore” and resolve the issue before it becomes a painful process to unwind, or to ensure that they aren’t duplicating work.

Documenting code is a great way to increase transparency

Software development projects are notorious for their lack of useful documentation. When working remotely, documenting software becomes increasingly important as informal communication decreases while the increased friction can slow things down. Yet, asking developers to document their code may not be the best answer.

In Part 4 we will describe how we have tackled the documentation issue at CodeStream with a radical idea. We capture the interactions that take place every day among developers in tools like Slack, Jira, and GitHub and turn them into nuggets of wisdom that explain how the code works.

Developers Must Choose Collaboration in an All-Remote world (Part 2)

Claudio Pinkus — Wed, 20 May 2020 14:35:57 +0000

Introduction

In Part 1 of this series, we talked about how we need to take into account personal and human aspects of our all-remote life that are not about just business or our careers. We also pointed out that being a software developer is a privilege, and that we have the opportunity to contribute to society while sitting at home and applying our knowledge and creativity. Challenging times are often the right moment to re-examine what we take for granted. We believe there is room for improvement in our software development processes, and now is a good time to start. In this article, we will begin to look at what drives dev team performance, and how our culture has been resistant to adopting a more collaborative approach for historical and competitive reasons. We will describe ways in which we, at CodeStream, have learned to tackle these issues and the impact we are seeing as a result of our approach.

We don’t collaborate enough

Over the past two years, we have talked to about 2,000 software development teams in an effort to understand how their toolset, their workflow, and the opportunities for performance improvement. If you are like over 80% of the teams we talked to, this is what your toolset and workflow look like:

The team plans the sprint on a Monday and developers mostly stay focused on your assignments until the end of the sprint, usually a week, with relatively little collaboration until the code is done.
You ask questions ad-hoc, sometimes to the developer sitting next to you, sometimes on Slack or Microsoft Teams. Mostly, though, you just try to figure it out on your own. There are no incentives to collaborate, other than at code review time.
You use GitHub, GitLab or Bitbucket for version control and code reviews.
You assign work through Jira, Trello, Asana, or something like it. Most often, all assignments start in your task management service. You complete your assignments largely without collaborating with anyone on your team.
Overall, you have little visibility of what your teammates are working on at any given moment.

If this seems right, it all makes sense because we are so used to the process. What parts of this can be improved upon in an all-remote mindset and context? To start with, how often do you check with your team or your reviewer on whether the feature you are starting on is on the right path? How often do you suggest a change to a teammate to improve code quality? If the answer is rarely, or even just once or twice a day, you are not optimizing your process for collaboration purposes. In particular, if you are used to resolving issues by just tapping someone on the shoulder or asking out loud in a room with your teammates, a new approach is required. Let’s tackle each of the bullets above through a collaborative lens.

There is no shame in asking

Most developers take pride in solving problems on their own. Perhaps it’s a badge of honor, or given the fact that we live in a competitive environment, it feels like asking will reveal some weakness on your part. As a team, at CodeStream we have created incentives to ask more questions more often, and we reward this type of exchange in public, reporting participation on our weekly all-hands. A customer of ours is planning on tieing part of the developers’ bonuses to the collaborative contributions made, whether asking a question or providing an answer. You should consider how your organization can promote more openness in code discussion.

Still, in a remote setting, the tools commonly used today for code discussion are particularly sub-optimal. Using something like Slack or MS Teams results in ephemeral exchanges that do not add to the collective knowledge and require significant effort to provide the context that was stripped away by copying a code block and pasting it into a chat stream. Further, since the question itself is likely to quickly scroll off the screen never to be seen again, these solutions don’t offer the persistence and accessibility needed in an asynchronous remote world.

We built CodeStream to solve this by attaching questions and replies to the code block(s) they refer to and then sharing this in Slack, MS Teams or email to leverage your existing communication tools. CodeStream is the in-editor bridge that makes these discussions more frequent and more useful to the whole team.

The pull request is great. For code reviews, we can do better.

Virtually every modern development team we have talked to since 2019 performs code reviews using the built-in tools of GitHub, GitLab, and BitBucket. Large organizations like Google and Microsoft have developed their own tools to conduct code reviews that are not PR based. At Google, they have standardized on a uniform toolset with a strong focus on speeding up reviews by making them as small as possible. Google reports that its average code review is just 24 lines of code and gets turned around and into production in 4 hours or less.

We believe they have the right philosophy and the right results. There are many benefits to small and fast reviews. Productivity increases, frustration is reduced, small mistakes don’t turn into large messes, and perhaps most importantly it allows larger teams of developers to weave changes together with minimum conflict. What does it take to make this happen in your organization? Pull requests don’t make it easy to review code. To start with, reviewing code in a browser instead of the IDE introduces the same type of context problem we discussed above with Slack, an unnecessary context switch. In addition, much frustration and effort can be eliminated by asking for reviews early and often, even on uncommitted code.

At CodeStream, we have built a solution that makes this super easy. We just package every change made by a developer in their editor, organize it and size it, and let the developer decide which parts to submit for review. The reviewer can then see all the changes in context, in their editor, attach comments as necessary, and approve or reject the work on a file by file basis. Our team is now conducting 10+ reviews per day per developer, and our velocity has increased by over 20% since we started this process.

Transparency and visibility

Working remote brings new challenges in the area of visibility. Not only can we not see each other in the office anymore, but it’s harder to work towards alignment without the right tools. In order to get the right visibility, we must start with a philosophy of transparency. In an all-remote world, we must choose to let everyone see what we are doing because without it there is too much friction and we lose traction. GitLab has famously included Transparency in their Six Values. How do you implement transparency in your development process to get everyone on the same page? We will tackle that in part 3 of this series.

We are all Remote Developers: Working From Home (Part 1)

Claudio Pinkus — Wed, 20 May 2020 14:29:38 +0000

Introduction

This is the first article in a four-part series dedicated to helping software developers, managers and organizations adapt to the pandemic emergency and become all-remote. In this first article, we will focus on the basics. There are many lists available discussing the right toolset and the behavioral changes necessary to be an all-remote team or organization. This article is not about that. Here we will dive into the human aspects affecting all of us, and address some of the ways in which we can turn this unfortunate event into an engaging learning experience for ourselves, our team and everyone we interact with.

The world during the pandemic

First, a personal note. I am 63 years old, suffer from high blood pressure, and I am scared and concerned, like everyone else who knows what’s happening. You already know that there is much we don’t know. This event will affect virtually everyone on the planet in one way or another, and many factors, including our emotional reaction to what’s happening around us, will make the situation very challenging and potentially extremely challenging, both at home and at work. We are all distracted from our business and professional obligations for good reasons, and we need to allow for a measure of distraction as there will be many moments of intense focus on the worries we are facing.

In the context of work in particular, which is the general theme of this series, I urge all of us to practice extreme kindness and understanding during these difficult times. In terms of our professional activities, there will be delays, confusion, flared tempers, and a full range of emotions on display as we tackle working together remotely under these circumstances. Since we are mostly working from home, work-related stress can also spill over into our family life with no clear escape valve. Rather than inflame conflicts, it’s a good time to take a step back and diffuse situations. Just like the stock market has a fuse to avoid extreme buying and selling situations from getting out of control, we should all recognize that diffusing and restarting is the best path forward for both personal and professional outcomes.

The privilege of being a software developer

Software development is a privileged profession. Not only do we get to build magic, but we can do it from anywhere. With an Internet connection, we can stay professionally connected and productive. Programming is intellectually engaging, so it’s relatively easy to lose yourself in the problem you are trying to solve, providing both a needed distraction and a real purpose. Developers usually work as a team, so you feel like you are part of something bigger than yourself, which also helps with motivation, engagement and emotional balance. So, while we cannot set our worries aside, we can spend part of our day focused on building something that matters now and will matter in the future.

Take a moment every day to be thankful for this privilege. In good times, the ability to stay home with your family while you work is a nice-to-have. In the current situation, all these amazing technologies we have been building in the last 30 years are holding us together, allowing us to stay productive, and support the creation amazing new products and services that you will be part of. What a great opportunity.

Every developer is now a remote developer

At CodeStream, we have been remote since Day 1. In fact, our team has been working remotely for more than 20 years, over the course of four different startups, since before Zoom or the iPhone even existed. Because we have built a strong culture around remote, we have never felt disconnected or lonely. Because we understand that not everything about working remotely can be accomplished by using Zoom alone (by the way, we love Zoom), we have always worked extra hard at forging the bonds that sustain us during hard times.

Over those 20 years we have had several hard moments, even if they do not seem that hard by comparison in light of the moment we are living through now. We have been together through deaths, divorces and illnesses, and we have always found a way to bring the human element back into the professional environment to make us stronger and more resilient as a team.

This is not the time to move fast and break things. This is the time to stay focused on doing the right thing, helping others, and finding strength in our common goals.

Let’s get to work

My next post will describe in detail the way our development team is working, including tips and tricks we have learned over the years. We believe there are many aspects of communication, integration, transparency and knowledge sharing among software developers that could use some improvement, and the fact that we are all remote now is an opportunity to improve on those deficiencies. In the meantime, if you would like a preview, here is a short post that you might find helpful.

The Connected IDE: A communication-first approach drives collaboration (Part 2)

Claudio Pinkus — Sat, 16 May 2020 15:33:36 +0000

Introduction

In Part 1 of this series we touched on the evolution of IDE from a personal, standalone tool to a connected and networked hub of all things code. We explained how connecting your IDE to your teammates’ simplifies communication and collaboration with two specific use cases: Discussing code in general, and performing code reviews right in your IDE, eliminating the context switching and improving knowledge sharing.

In this post we will expand this to additional use cases and show how the Connected IDE is the most important step towards team collaboration in a world where we are all remote developers.

What is collaboration anyway?

There are many flavors of collaboration platforms and tools for developers, and many permutations through extensions. In the context of making your IDE more connected, we look for collaboration to enhance velocity and value for the team. In a post updated on November 24, 2019, Geoff Stevens writes about How to collaborate like a pro in VS Code. Since VS Code is today the most popular modern editor, we will focus on it as an example, but the analysis applies to much of the collaboration approach out there.

In the post, Geoff looks at a list of VS Code extensions that bring collaborative features into the editor. These include, among others:

Microsoft’s own Live Share that “eliminates the friction of coding together by letting you collaboratively edit, debug, and fix code in real-time without leaving the comfort of your own VS Code setup,” according to Geoff. Live share is pair programming inside VS Code, and provides an experience that is reminiscent of screen-sharing, but specifically for developers.
CodeStream, which “allows you to comment, ask questions, and have discussions across your codebase from within VS Code.” Note that CodeStream now also allows you to perform code reviews in your editor.
The Jira extension for VS Code gives you the ability to “view, search, and filter issues in Jira inside VS Code.”
GitHub Pull Requests that helps you review and manage GitHub pull requests right inside VS Code.

We believe that collaboration starts with communication between developers. Through that lens, only Live Share and CodeStream are actually delivering collaboration, while the GitHub and Jira extensions serve only to reduce friction for the individual developer by reducing context switching. We believe collaboration is a communication-first endeavor. The ability to view or reference other content inside my IDE makes it easier for me to collaborate with my team, but only in communicating am I actually explaining my intent and resolving conflicts, misunderstandings or misalignment. A communication-first approach drives velocity and code quality.

Code needs to be a first class object in communication

In order to reduce friction and simplify communication about code, the code itself needs to be a first class object in the communication exchange. In part 1 we discussed the difference between a Personal IDE and a Connected IDE approach to asking a question or performing a code review. Here we will present a couple of use cases that illustrate how a tool like CodeStream allows code to become a first class object because your IDE is now connected.

Suggesting an improvement

Personal IDE: You come across some code that you believe could use some improvement. You don’t want to take this on as a project, nor do you want to change someone else’s code without communicating with the author. You copy and paste the code in question into Slack or MS Teams, explain the context (repo, file, line number, etc.), type the code you suggest replacing it with, and explain why you think it’s a better approach. Upon receiving your suggestion, the author needs to locate that code in their IDE, review your suggestion, get back to Slack, discuss it with you, copy and paste the final suggestion (if modified) into her editor and push it. If this happened once, perhaps the friction would be tolerable. But there is just as much friction the second time you have a suggestion, and a third.
Connected IDE: You see code you believe could use some improvement. You make your suggested change in your IDE. Then you highlight the code block in question and add a comment in CodeStream such as, “is it safe to short-circuit the loop here? It would make this function much more performant”, like this:

When the author gets the notification, she can just do a diff in her IDE and apply the patch if she finds it useful, like this:

Connecting related code:

Personal IDE: Let’s say you want to point out to your teammates that different parts of the code you are writing are related. Perhaps you want to indicate the part of a React component that isn’t interacting with your stylesheet in the way you would expect. You would choose a file, jira ticket, or slack thread to communicate this outside your IDE and assemble there the list of permalinks that point to those code blocks in the different files. Whenever you or anyone on your team wants to make a change, you would have to try to find that external resource with the permalinks.
Connected IDE: If you want to connect different parts of the code and share that information with your team, you can just make a comment on one of the codeblocks and add the different ranges in other files and even other repos that are connected to that original range, like this:

The Connected IDE enables knowledge sharing

Coding Sans conducts a Development Trends Survey every year, and for the past two years the #1 challenge for developers is Sharing Knowledge. It’s very telling that the issue of knowledge sharing remains so challenging. The personal IDE, where each individual developer produces code remains an island detached from colleagues and teammates, so extra effort must be applied to share information about the code being produced. We already covered the fact that documentation is not common among development teams. The Connected IDE provides an opportunity to finally address knowledge sharing in an effective and ubiquitous way.

The Connected IDE is the gateway to increased developer collaboration (Part 1)

Claudio Pinkus — Sat, 16 May 2020 15:29:38 +0000

Introduction

Like the standalone PC’s of the 1980s, the personal IDE remains an island detached from the opportunity to improve collaboration for the development team and the company as a whole. A new era of connected IDEs is coming that does not require you to leave behind the IDE you love. Using modern plug-in technologies, your IDE can begin to evolve towards a truly Integrated Development Environment that will make collaboration easier while improving code quality.

History

In the beginning of the personal computer revolution, circa 1975, the IDE was invented. It was called Maestro I and it was the first “modern” development environment. The Integrated aspect of the IDE refers to the combination of a source code editor, build automation tools and a debugger. Since then, a plethora of IDEs have been developed ranging from VI and VIM to Emacs, Visual Studio, Sublime and VS Code. The term has evolved to refer both to the source code editor as a standalone tool, as well as the more complex environments that integrate multiple tools.

A more modern concept of integration refers to the ability of an application to connect to another, typically developed by another entity or company. For instance, the Jira Integrations page displays a collection of hundreds of third party applications not produced by Atlassian that connect through APIs to Jira. Let’s explore now the state of the IDE world.

The modern Connected IDE is taking over

Much has changed in the last 5 years in the IDE world. When Stackoverflow asked developers to select their favorite editor/IDE in 2015, these were the results (Note that you can vote for more than one editor, so totals can add up to more than 100%):

Sublime and NotePad++ were leading the pack, while Atom, a product of GitHub was just emerging as the first truly extensible editor. Atom was built on Electron, and was touted as A hackable text editor for the 21st Century.

In 2017 the state of the IDE had already changed significantly:

While the question itself had changed (now segmenting web/desktop/sysadmin), the top dog was now Visual Studio for both Web and Desktop development, while Atom moved up to 20% and IntelliJ to 23%. Visual Studio and IntelliJ charged for their editor, while Atom was free to use and Open Source.

By 2019, the picture had changed again, now with a new leader from Microsoft:

Visual Studio Code, an Electron-based Open Source free editor is now the #1 IDE in the world, and it’s very extensible. Atom has fallen off and will probably continue its decline in 2020, now that GitHub (publisher of Atom) is also owned by Microsoft. All modern editors now support plug-ins, and therein lies the collaboration opportunity: The connected IDE.

From the Personal IDE to the Connected IDE

Most developers today continue to code in a Personal IDE mode. When it’s time to ask a question or have someone review their code, they move it over to a different environment, outside their IDE, losing context and unnecessarily introducing friction. This is a big deal because quality and productivity suffer. At CodeStream, we have interviewed over 2,000 development teams to find out how they go about producing code. Let’s take a look at two scenarios that benefit drastically from having a connected IDE.

Asking a question:

Personal IDE: Before we all began working remotely, a tap on the shoulder was probably the most common way to ask a question. Now, if a developer has a question, she will copy and paste the code in question into Slack or MS Teams (or even take a picture of their screen!), explain the context (repo, file, line number, etc.), find the right person or channel to ask, and when she gets the answer, that interaction will soon scroll off the screen in an ephemeral chat stream that will not contribute to sharing knowledge within the team.
Connected IDE: She can just select the code in question, comment on it (like you do in Google Docs), select who to share it with (the context is self-evident here, so no explanation needed), get the answer, and everyone on the team can now benefit from that knowledge, like this:

Requesting a Code Review:

Personal IDE: Most developers use GitHub, GitLab or Bitbucket to request a code review. That is also where the reviewer performs it. It may feel like that is the right environment for this discussion but in fact, it introduces multiple points of friction that make code reviews slower and harder. 1) It takes you out of your natural coding context by moving the discussion to a web browser, where understanding code is unnecessarily difficult. Why would you want to limit the amount of visible code to just a snippet? If you need to get more context, you need to go back to your editor. And to know what’s happening, you still need a notification tool, like email or Slack. In addition, 2) It forces the author of the code to predetermine what should be reviewed by establishing the PR as the earliest possible time for a review. What if I just want some feedback on WIP or uncommitted code?
Connected IDE: As your IDE is already connected to your reviewers’ IDE, the steps are simpler and shorter. First, you do not have to switch context. Your IDE knows exactly what changes you have made. Some may be ready for a formal review, others just for a quick check on general direction. Your IDE can package up every change automatically, ask you if you want to remove any changes from the package and make the request for a review to your preferred reviewers, notifying them through Slack, MS Teams or email, or even easier, just seeing a badge in your IDE letting you know that a review is awaiting. The reviewers can perform the review in their connected IDE and see exactly the state of the code in the author’s editor. The reviewer can comment, suggest, and question with full context. The review can be completed even before a PR is created. Easier and faster. Like this:

In the future, every IDE will be Connected

Atlassian, one of the world’s largest development tool companies, believes that teams are the foundational unit of the company’s culture. So strong is their belief in teams that the stock ticker for the company is in fact TEAM. But culture is only the first step in enabling teams to optimize their performance. As we will see in the next post, the Connected IDE has a big role to play in fostering a positive and productive team environment.

Reviewing the Code Review, Part II

Claudio Pinkus — Tue, 24 Sep 2019 17:26:36 +0000

In Part I, we discussed specific suggestions to improve code reviews using PRs, and how the methodology itself has inherent limitations. We asked:

What if you did not need a PR to start the review?
What if you could just tag and comment on any part of the code at any time?
What if you could link two otherwise unrelated parts of the code to highlight a dependency or illustrate an approach?

In this post we review the suggestions made by Jonathan Maltz of Yelp in his article Code Review Guidelines. They are similar to many other articles you can find on the topic, so they serve as a clear outline for this discussion.

A code review is a discussion

Jonathan points to general themes that tend to improve code reviews. These are some of his key messages:

Communication is key
Smaller is better
Make your code easy to review
Code reviews are a discussion, not a dictation
Time is of the Essence
Review for Correctness

Note that there is an overarching theme here that you can read between the lines. The PR is in fact determining the cadence. We are used to PRs defining what is possible. I will now suggest that there may be a better way to frame code reviews in the context of a continuous approach.

A Continuous Code Review mindset

At CodeStream, we are building the tools that allow code reviews of any portion of your code at any time without the need for a PR. We call that approach a Continuous Code Review and it is ideally suited to the DevOps era. Let's look at Jonathan's suggestions in the context of this mindset.

Of course, communication is key when reviewing code, since the only way to clarify issues and reach alignment is to communicate. But how are you communicating? Are you using Slack or Microsoft Teams, cutting and pasting code snippets and hoping to clarify matters outside the context of the IDE? Why not avoid context switching altogether and stay in your editor to communicate? That would simplify and improve the process.

Smaller is better is also a way of saying that small chunks are easier to understand, process and learn from. Why not make it as small as possible? What if you could just discuss and review any code block at any time without a PR? That would increase effectiveness and provide guidance without any of the trappings of the PR formality.

Make your code easy to review means providing guidance to the reviewer in advance. While that is desirable, it becomes less important when communication is easy in context, If your reviewer can ask or comment on your code and you can reply quickly and without context switching, you will not have to guess what the reviewer might be unclear about.

Code reviews are a discussion, not a dictation means that the reviewer is providing feedback, which may just be a need for clarification instead of a suggested change. But a good and efficient discussion requires great communication, and great communication about code cannot happen with a lot of context switching. See above.

Time is of the Essence refers to turning around the review to the submitter as soon as possible. The suggestion is no more than 24 hours to maintain momentum. Sure, there are many reasons why a review could be delayed, but generally, it's because the amount of code to review is too overwhelming to just knock it out in a few minutes. In a Continuous Code Review context, reviewer and reviewee would work though small chunks quickly so as to find resolution and clarity and maintain momentum. Issues can sometimes be resolved in minutes, not days.

Review for Correctness means making sure the code is bug-free and solves the problem at hand. But what if you could make suggestions about any part of the code that do not need to be resolved immediately and allow the code to be merged while also providing a mechanism to track areas of concern or improvement right along the code so that anyone who works on it can be informed of those concerns and address them appropriately?

Summary

The Continuous Code Review mindset implies a new set of assumptions regarding what to review, where to best communicate during the review, and when to do it. Here are the takeaways.

As you encounter code that might be improved, it's best to flag it right away. Not limited to whichever PRs might be open, but any code, at any time, on any branch, anywhere.
For this approach to be practical, it's assumed that you will be in your IDE, where talking about code is easiest, and that a PR is not needed. Otherwise, the friction just grinds the process to a halt.
Lastly, reviews should happen very frequently. As you work with the code, if you have a question, just ask it; if you see a problem, flag it; if you have a suggestion, describe it; If you have the answer to a question, offer it.

CCR represents an order-of-magnitude reduction of friction for code reviews. By allowing you to review, or ask for a review of any code in your codebase without a PR, and without leaving your editor, you have the opportunity to radically improve the code review process.

Reviewing the Code Review, Part I

Claudio Pinkus — Thu, 08 Aug 2019 13:53:44 +0000

Some of our customers are telling us that they are using CodeStream to shorten code reviews by as much as 50%. It’s a lightweight approach, and we are trying to learn from their experience and feedback, and improve on the processes and features we offer to make those code reviews even better. CodeStream introduces the concept of a continuous code review, a light-weight, in-editor process that enables the review of any part of your codebase, at any time. Making code review continuous means you can get feedback earlier in the process as you are stubbing out functions and classes, during heavy development while you are building a new feature, immediately prior to merge as you seek feedback from your team, and importantly even for code that was merged some time ago, as you come across technical debt in your codebase.

What’s wrong with code reviews?

According to Traci Lum in her article How to Give and Get Better Code Reviews, code reviews are among the most dreaded activities by developers. Developers, who typically spend much time creating, imagining, and inventing (often on their own and without interference), face an uncreative procedural judgment. She writes: “...it’s a time when you, the developer, the craftsman, the artist, present your work before a council of critics and beg them to bless your masterpiece with a thumbs-up emoji and a “LGTM.””.

Code reviews are, of course, necessary to maintain code quality. Why such dread? What can be done to reduce it significantly? What are the benefits of a different approach? Much of what’s wrong with code reviews boils down to three elements:

the time elapsed between code being written and code being reviewed,
the context switching imposed by the very process, away from the code and into the browser or to a different context outside your IDE, and finally
the fact that a typical review looks at any given code only once – it’s being readied for deployment – and does not contemplate a continuous improvement process.

In this context, let’s discuss some of the suggestions provided by Traci on how to improve the code review process, and suggest improvements to the improvements.

Developers generally live in their IDE. That is the place where code is written, changed, compared, etc. The reason why code reviews are not performed in your IDE is an accident of timing. Had IDEs been more extensible earlier, we would have seen all the benefits of performing code reviews in context and the disjointed nature of the process might have been avoided.

Your IDE is the best place to discuss code

Traci Lum’s suggestions are helpful and reasonable and they are centered on improving the PR process. Let’s summarize her recommendations while addressing potential improvements that could be made if the code review was started earlier and originated in your IDE instead of a PR.

If you want to get better code reviews, her suggestions include:

Linking to the GitHub issue or JIRA ticket from the body of a PR
- What if there was no PR and you could instead generate or attach a Jira ticket or GitHub issue to the code itself from your IDE, assign someone to fix or review, and have that link be permanent and visible to any teammate perusing the code?
Writing a quick summary or list of the changes, trade-offs, and remaining todos
- What if the summary of the changes was just an automatic report being generated within your IDE including all the questions and concerns?
Tagging pull requests with labels, and Review your own code before you officially put it up for review
- What if you could tag and comment on any code block and make that easily accessible in editor for all the devs in your team?
Annotate places where you’re especially unsure or want feedback
- What if you could just do that at any time as you write code, even before a PR, so that the feedback can help you avoid a dead end, thus reducing errors and technical debt?
Tag the right people
- What if once you select any code block in your IDE there was an instantaneous git blame lookup to let you know who wrote or edited that code and that person was @mentioned in your composition box automatically?
Take a breath and internalize the reviews.
- Always good advice. What if the whole conversation was saved and accessible to both parties (and ultimately to any dev on the team) as useful documentation that explains how decisions were made?

If you want to give better code reviews, her suggestions are:

Ask questions instead of making statements, that is, fewer WTFs
- What if you could share a code example to illustrate a solution and it was linked to the review automatically?
Articulate the problems (if any) and suggest alternatives
Try to understand the context and the proposed solution
Highlight wins (by which she means, be positive when giving feedback)

If the PR is to remain the primary place where a code review takes place, all of the steps suggested by Traci in order to improve the process would be fine. However, if we are prepared to consider beginning the review process earlier, prior to a PR, unencumbered by the PR, the code review becomes continuous, that is, at any time, on any line of code, about any issue.

In Part 2, we will explore other suggestions for improving the code review, and offer ideas on how to make things even easier, more productive, and more pleasant.

Knowledge Sharing Leads to Developer Team Productivity

Claudio Pinkus — Fri, 21 Jun 2019 18:46:39 +0000

Companies are increasingly focusing on the software development team as a driver of productivity gains. Addressing the drivers of team productivity, as opposed to individual developer productivity, requires a different perspective and methodology. And it starts with sharing knowledge, since the knowledge gap between different developers may lead to unnecessary drags on overall productivity, even if it makes some team members more likely to appear a lot more productive than others.

First, some background on the business concerns that are accelerating the focus on the dev team. Development team performance is becoming so central to business that it’s become an important topic in boardrooms around the world. In March 2019 Morgan Stanley published a report entitled “A New Software Stack for the Digital Era” in which they describe a transition from the Old Stack (think Oracle, Tibco, Old Microsoft) to the New Stack represented by companies like Atlassian, PageDuty, Splunk, MongoDB, and New Microsoft. According to the report, the New Stack represents a $50B opportunity with 22% vs. 4% CAGR when compared to Old Stack growth, driven by the wide adoption of DevOps and Agile methodology. Morgan Stanley’s definition of DevOps is as “any practice, methodology or architecture that reduce or alleviate the inefficiencies in the process of delivering new features and services to end customers.”

From a more technical perspective, DevOps is a software development strategy that bridges the gap between the developers and the IT staff. With DevOps, organizations can release small features very quickly and incorporate the feedback they receive. This results in 1) Fewer software failures and 2) Shortened lead time between fixes – i.e. higher productivity. For all of this to work as intended, knowledge sharing is often a missing link.

Knowledge Sharing is Top of Mind

According to the State of Software Development report in 2019 by Coding Sans, the second biggest challenge tech companies are facing is knowledge sharing – right after capacity. Typically, knowledge sharing suffers when the backlog is full and the deadline is approaching. In other words, in a world where developer demand outstrips developer supply (as is the case for the foreseeable future), alleviating the inefficiencies is dependent largely on the ability of the organization to share knowledge.

The report also points to a difference between management and developer perspectives of the most significant challenges in 2019. For developers, Knowledge Sharing is the most important challenge they face at 24.57% of the respondents, up from 18.11% in 2018.

If sharing knowledge is so important, how do teams tackle that fundamental challenge today? The Agile process places strong emphasis on face-to-face conversations for conveying information, but is that the same as having a comprehensive approach to sharing knowledge? With teams distributed across many time zones, conversations are increasingly not enough. What will supplement or replace these face-to-face conversations?

Remote is the New Normal

Remote is increasingly becoming commonplace among developers in organizations of every size. According to the same report, 72.2% of developers report that remote work is allowed in their organization.

Organizations with remote developers often turn to solutions such as Skype or Zoom that can easily replace a face-to-face conversation. A conversation in Slack or Microsoft Teams where knowledge can be shared asynchronously – and tediously when it comes to code – can also answer questions and share knowledge. However, these approaches do nothing for the team or the organization in terms of capturing and organizing that shared knowledge so that it may be easily accessible a month or a year from now. They lead instead to repeated and wasteful interactions as the same issues and concerns are raised again and again, or worse, they become barriers for new developers who are afraid to ask a simple question for fear of becoming an annoyance to more senior team members.

Team Productivity and Sharing Knowledge

Developers know that there is a relationship between the team’s ability to share knowledge and its ability to be more productive – as a team. There are different kinds of knowledge that a team can share. The first kind, general knowledge about coding, can be conveyed in posts, papers, webinars, books, etc. and can be helpful in lifting all team members to a common understanding of the approaches and methods the team embraces. For instance, Davide de Paolo writes in his post What makes a 10X developer? that among the characteristics of a rockstar is knowledge sharing: “As soon as you learn something, try to help someone else, teach other colleagues, share your learnings. It can be giving some advice after your daily standup, making a short presentation to your team, writing a blog post or becoming a mentor on an online coding platform.”

A second kind of knowledge is specific to the code itself. It is not possible to acquire this kind of knowledge by posting a question on Stack Overflow or Quora, since only your team members might know the answer, and further, security concerns may require the code to be discussed only internally.

Many developers report frustration at spending a large percentage of their time – sometimes up to 75% – trying to understand code written by someone else. Less than 20% of developers in Stack Overflow’s 2018 survey state that they use the company’s internal documentation in trying to figure out how the code they are working on works. In the context of team productivity, how should this kind of knowledge be shared?

Sharing Knowledge about Your Code

For this second kind of knowledge to contribute to team productivity, it must meet four criteria:

It must be easily accessible at any time
It must be contextual
It must be persistent
It must allow for interactivity that will further clarify its meaning and applicability

It’s time for knowledge about your code to move from isolated and disparate sources to the code itself. Knowledge in context is more easily understood. Teams must set aside notions of code that explains itself and adopt instead solutions and technologies that address the knowledge gap and lift the whole team to higher ground. Shared knowledge then becomes a competitive advantage for the whole organization.

You might think code comments might take care of this, but that is not the case. Code comments have been used for a long time to explain how the code works, but they suffer from three major drawbacks: 1) They become stale relatively quickly as the code evolves, 2) they are not conversational, and therefore are not great for iterating around an explanation, and 3) you cannot easily ask a question using a code comment, and questions are perhaps the most important element of knowledge sharing. That’s because whoever is explaining his or her own code does not know in advance what aspects of the code will not be easily understood by another developer. Therefore, the ability to ask questions within the code leads to better quality and better documentation.

Teams who are concerned with capacity and knowledge sharing should therefore look for solutions that meet the above four criteria and fit within their existing workflow and toolset. Sharing knowledge within your favorite IDE should simplify conversations about code, while integrations with your preferred messaging and issue tracking software will allow developers to stay in context while notifying the whole team when new questions and answers are being created.

Summary

Team Productivity is achieved when team members share knowledge widely. Developers already feel the pain if too little knowledge being shared and rate this as their number one concern. Traditional face-to-face conversations can help address certain kinds of knowledge, but with remote becoming mainstream, new solutions are required that address both the immediate need and the long term need for knowledge sharing. Specific information that describes how your code works should not be divorced from the code itself, as it makes that information less usable and less understandable. The next wave of solutions and tools for developers must address the knowledge gap and lift the whole team towards greater productivity.