An Introduction to Codemarks
and Your Knowledge Base
Codemarks are the building blocks of your team’s knowledge base. A codemark captures a discussion about a block of code, and remains anchored to the code so that the discussion can be surfaced later
Ask a question. Help a teammate. Identify issues. Codemarks are flexible tools for simplifying your workflow. But, the real power lies in the knowledge base that they collectively represent, and that gets built up effortlessly over time. Create a codemark by selecting a block of code in your editor and then typing a question or comment. Keep in mind that, unlike with other solutions, 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 saved or committed. Get instant feedback form your teammates without having to go through a formal process.
CodeStream supports four different types of codemarks
The all-purpose codemark for linking any type of discussion to a block of code. Some examples are:
- Ask a question. Leverage your teammates’ knowledge to get help with code you’re struggling with, trying to debug, or simply trying to understand.
- Document important or complex areas of code. Unlike inline comments, codemarks are conversational. You can clarify, add additional commentary, reply, @mention, and all of the usual interactions you typically use in modern chat services.
- Point or direct a teammate to some code. We all get asked where a specific piece of code is or where some behavior or feature is implemented. With codemarks, you can very quickly and easily provide a direct link to that code all directly from your editor.
When something needs to get done, either by you or someone else on the team, there’s always a better chance of it happening in a timely fashion (or at all!) if it’s captured as an issue.
- See a problem with an implementation? Assign an issue to get it changed.
- Debugging some specific issue and find more (maybe unrelated) bugs? Quickly select the offending code and create a codemark to make sure these bugs won’t go untracked and you can get back to focusing on the original issue.
- Need some code reviewed? Assign a specific reviewer, and discuss feedback in the thread.
- Remind yourself to come back and fix something by assigning yourself an issue instead of adding an inline “FIXME” comment.
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. For example, in a Jira ticket, a PR comment, or a Slack thread. Permalinks give you a URL that you can share anywhere, and you can decide whether or not authentication is required to view the web page depicting the code.
Highlight notable or important parts of the code, or simply parts you want to be able to get back to quickly.
- Bookmark blocks of code you update frequently for quick access.
- Implementing a feature with many code touch-points? Leave yourself bookmarks with the pieces left to be done.
- Working with a junior developer or one unfamiliar with how a bug or feature should be fixed or implemented? Share bookmarks with them to note the places in the code to look or where parts of the feature should be implemented.
Source File Annotations
Codemarks are displayed as annotations to your source files, with an icon (based on the type of codemark) displayed right next to the code block to which they refer.
These annotations ensure that the right person sees relevant codemarks at exactly the right time and place. Whether you’re about to debug, rewrite, or review, the annotations in the source file will make you immediately aware of past discussions about the code, and reviewing those discussions will give you context to shape the work at hand. Hover over a codemark’s icon and then click, and you'll be taken into the discussion thread.
Click on the Codemarks tab to explore your team’s entire knowledge base. Sometimes you might want to quickly review all of the codemarks in a given file, or all of the codemarks of a certain type.
As you move from file to file in your source tree, the “In This File” section summarizes the codemarks in the currently selected file. And to make sure you’re always aware of what’s on your plate, the “Open Issues Assigned to Me” section lists any open issues assigned to you.
Look for the search icon at the top-right of the page to search for codemarks based on a keyword.
Armed with codemarks and a knowledge base, CodeStream improves every aspect of software development. Learn more about how your team can leverage CodeStream in these 8 Scenarios CodeStream Improves