Discuss code using CodeStream codemarks

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.

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.

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. Green, purple, and gray icons are used to represent open, resolved and archived codemarks respectively. 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.

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 comment to share it anywhere. When someone clicks the permalink they'll automatically be redirected through the web to their IDE, where the discussion is automatically opened.
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.
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.