Discuss code on CodeStream

What is a codemark?

Quite simply, a codemark is a discussion connected to the code. It could be a question, a suggestion, a bug report, or documentation. All of these discussions are saved, anchored to the blocks of code they refer to, so that they can be leveraged in the future. It could be a new developer joining the team, a developer trying to fix a bug in someone else’s code, or even just you trying to remember why you made that change six months ago. Whatever the case, CodeStream helps you understand the code by surfacing the discussions in a contextual way.

Even as a file changes over time, the codemarks remain connected to the code. Add some new lines of code above the code block, make edits to the code, or even cut-and-paste the entire block to a different section of the file, and you’ll see the codemark move along with your changes.

Here's a short video (3:15 minutes) showing how a team can use codemarks to collaborate on code in their IDE:

Codemarks overview

The codemarks section of the CodeStream pane lists all of the codemarks in your current repository for easy reference.

Click any item in the codemarks section to review its details and discussion. With the exception of pull-request comments, bubbles to the right show the number of replies.

By default, all codemarks from the current repository are displayed, but you can change the filter to show all codemarks in the current branch, codemarks in the current folder, or codemarks in the currently selected file.

Codemarks from feedback and pull requests only appear when you've selected the current file filter.

When you hover over the codemarks section heading, the following icons appear at the right:

The codemarks header includes options to create a code comment or issue. You can also choose to view the codemarks in a spatial view, instead of in a list. The discussions are displayed alongside the blocks of code they refer to, and as you scroll the source file the discussions scroll as well.

Click the gear icon for more controls over the list.

• Wrap multi-line comments: Rather than showing a truncated portion of the codemark, the list shows the whole post is displayed.
• Show tags: Any applicable tags will be displayed with each codemark.
• Sort comments by: By default, Codemarks are ordered by date, but when the filter is set to current file you can sort by line number (such as, their order in the file).
• Show icons in editor gutter: In addition to appearing in the list in the codemarks section, codemarks are also represented as icons in the editor gutter alongside the blocks of code they refer to. You can determine which types of codemarks, and which statuses, you want to have displayed there. By default, codemarks from feedback requests are displayed, but pull request comments are not. Resolved codemarks are also displayed by default, but archived codemarks are not.

Create a codemark

To create a codemark, select a block of code in your editor and then click one of the icons that appears in the CodeStream pane next to your selection.

If you're using a JetBrains IDE, such as IntelliJ, you can also create a codemark via the + button that appears in the editor's gutter when you select a block of code. When you're viewing a diff, for either a feedback request or a pull request, the button will also appear when you hover over the gutter to make it easy to comment on a single line.

Even when the CodeStream pane is closed or not in view, you can create a codemark via the CodeStream options in either the lightbulb or context menus.

You can also look for the + menu at the top of the CodeStream pane.

Need to reach teammates that don’t spend a lot of time in the IDE? Or maybe some teammates that aren’t yet on CodeStream? You can optionally share a codemark out to Slack or Microsoft Teams. The Slack integration even allows your teammates to reply directly from Slack.

Comment codemarks

Comment codemarks are the all-purpose codemark for linking any type of discussion to a block of code. Ask a question. Make a suggestion. Document some code. Make note of key sections of the codebase. The possibilities are endless.

Issue codemarks

When something needs to get done there’s a better chance of it happening if it’s captured as an issue with someone’s name attached. Assign issues as a way of reporting bugs or manage your tech debt by capturing items as tracked issues instead of inline FIXMEs.

If your team uses Asana, Azure DevOps, Bitbucket (cloud), GitHub (cloud or Enterprise), GitLab (cloud or Self-Managed), Jira (cloud or Server), Linear, Shortcut, Trello, or YouTrack (cloud) for tracking issues, you can create an issue on one of those services directly from CodeStream. Select the service you use from the dropdown at the top of the codemark form.

After going through the authentication process with the selected service, you can select a destination for your issue. For example, with Jira you'll be able to select the appropriate issue type and project.

Once the issue has been created on CodeStream, it includes a link to the issue that was created on the external service. In the example, you'll see the URL for the issue on Jira.

The issue on Jira includes a link to open the relevant code in your IDE.

Bring the right people into the discussion

When you create a codemark, CodeStream automatically mentions the people that most recently touched the code you're commenting on. They may be the best people to answer your question, but you can, of course, remove those mentions and manually mention someone else if appropriate.

It may be the case that the people that have touched the code aren't yet on CodeStream, in which case CodeStream will provide checkboxes to have them notified via email. They can reply to the email to have their comment posted to CodeStream and, of course, they can install CodeStream to participate from their IDE.

Work with different versions of the code

Maybe you're on a feature branch, have local changes, or simply haven't pulled in a while. There are countless reasons why the code you're looking at might be different than what a teammate is looking at. As a result, there will be plenty of times when the code referenced in a codemark doesn't match what you have locally.

CodeStream recognizes these situations and includes the original version of the code block (such as, at the time the codemark was created), the current version, and a diff.

Keep in mind that with CodeStream you can discuss any line of code, in any source file, at any time, even if it's code that you just typed into your editor and haven't yet committed. CodeStream empowers you to discuss code at the very earliest stages of the development process.

Resolve codemarks

Although not required, both comment and issue codemarks can be resolved. The codemarks section of the CodeStream pane breaks out codemarks into open, resolved and archived sections. Green, purple, and gray icons are used to represent those different states. If you see a lot of open/green codemarks in the CodeStream pane, that means that your teammates are being blocked by discussions and issues that haven't been resolved.

You can add a comment at the same time you resolve the codemark and you can also archive the codemark at the same time.

Advanced features

Advanced features include multiple range codemarks, file attachments, tags, and related codemarks.

Multiple ranges

Many discussions about code involve more than just one block of code and concepts are often best presented when you can refer to multiple code locations at once. Here are a few examples of multi-range codemark at work:

• A change to a function is being contemplated that will impact its name. Each instance of the function call can now be referenced in one discussion.
• A React component and its CSS styling aren’t interacting well and you want to ask the team for input. You might select the div and the CSS rules you think should apply, so your teammates know exactly what you’re talking about.
• Clients which make API calls to the server might get an unexpected result. Select the code where you’re making the API call, and the handler in the API server, to connect the two actions together.

To create a multi-range codemark, click + Add Code Block.

Then select another block of code from the same file, a different file, or even a different repo.

You can intersperse the difference code blocks in your post by referring to each one as [#N] (or click the pin icon from one of the code blocks to insert the markdown for you), as in the following example.

Here's how that example is rendered.

Once you've created the codemark, you can jump between the different locations by clicking the jump icon at the bottom right of each code block.

When you edit a codemark, you can add and remove code blocks and you can change the location of any of the code blocks by clicking the dashed square icon.

File attachments

Enrich your discussions about code by attaching files directly to code blocks. Think about how much more compelling your comments and documentation become when you attach:

• A spec to guide the development of a new feature.
• A log file to help debug an issue in the code.
• A mockup to help clarify some UI work.
• A screenshot to highlight a problem.

When creating a code comment or issue, you can attach a file by dragging-and-dropping onto the description field, pasting from your clipboard, or by clicking the paperclip icon.

Images can even be displayed inline using markdown. Click the pin icon to the right of the attachment and CodeStream will insert the markdown for you.

Now your teammate knows exactly what you're looking for:

You can click on files in the attachments section to either download it or open it in the appropriate application.

Add tags

Look for the tag icon inside the codemark compose box to either select a tag or create a tag using any combination of color and text label.

Tags are a great way to broadly organize and group your organization's codemarks and the possibilities here are endless.

You can also filter by tag on the Filter & Search page.

Related codemarks

Click the CodeStream icon in the codemark compose form to select other related codemarks to attach them to the current codemark. This establishes a connection between different parts of a codebase. For example, when a change to one part of the codebase would require a change to another part, identify the dependency by creating two related codemarks.

Once you’ve added the related codemarks they’ll be displayed in a related section and you can click on any one to jump to that codemark and the corresponding section of the code.

Manage codemarks

Click the ellipses menu for any codemark and you'll see options to manage the codemark.

• Share: In addition to sharing to Slack or Teams at the time you create a codemark, you can also share it anytime later.
• Follow/Unfollow: Follow a codemark to be notified when its updated. Unfollow to stop receiving notifications.
• Copy link: Get a permalink for the codemark to share it anywhere.
• Archive: If there's a codemark that you don't think is important enough to be on permanent display in a given file, but you don't want to completely delete it, you can archive it instead. Settings in the codemarks section allow you to easily see all archived codemarks.
• Edit: Only the codemark's author can edit it.
• Delete: Only the codemark's author can delete it, but we encourage you to archive instead of deleting unless you're positive the codemark won't have any future value.
• Inject as Inline Comment: If you'd like a specific codemark to become part of the repo use this option to have it added as an inline comment. You can select the appropriate format, and then indicate if you want to include timestamps, replies, or to have the comment wrapped at 80 characters. You can also elect to have the codemark archived once it's been added as an inline comment.
• Reposition codemark: In most cases, a codemark will automatically remain linked to the block of code it refers to as the file changes over time. For example, if you cut the block of code and paste it at a different location in the file, the codemark will move right along with it. There are some scenarios, however, that CodeStream isn't able to handle automatically. For example, if you pasted the block of code into a different file. In these cases, the Reposition codemark allows you to select the new location of the block of code so that the codemark is displayed properly.

Permalinks for sharing anywhere

Whenever someone clicks the permalink, after authenticating with CodeStream, they'll automatically be redirected through the web to their IDE, where the discussion is automatically opened. In the case of a comment or issue, the source file opens and scrolls to the corresponding block of code.

CodeStream does its best to determine which IDE to open, largely based on the IDE that you last used to access CodeStream. However, you can always return to the web page that was opened and select any IDE you'd like to use. Your selection will be remembered the next time you open a discussion associated with the same repository.

If you're using a JetBrains IDE, install the Toolbox app so that CodeStream can deep link into the IDE.

Permalinks for code blocks

Sometimes you don't necessarily want to comment on a block of code, but instead just want to easily share the code with a teammate. CodeStream's permalinks are living links that always point to the code in question, even if it's moved to a different location in the file.

Select the code in your editor and then click the Get Permalink button to get a permalink for that code.

• Decide whether you want the permalink to be public or private, with private permalinks requiring CodeStream authentication before the code can be viewed.
• Copy your permalink and paste it anywhere you'd like to share the block of code.
• Like with comments, issues and feedback requests, whenever someone clicks the permalink, they're automatically redirected through the web to their IDE, where the source file will be opened and scrolled to the corresponding block of code.