Swimm's Regex-based Rules is a feature that links your codebase to relevant documentation using regex rules. You can customize these rules based on your unique needs, enhancing your understanding and navigation of the codebase from the very first day. AI-assisted rule creation also suggests use cases and regular expressions. This guide will walk you through the entire process from discovering use cases to managing your rules.
Rules appear on a regex match. That applies to existing code and as-you-type code.
In JetBrains, there might be a lag until the code highlighting appears under the matching code.
Create a new rule: In your IDE, open Swimm's plugin. Here, you'll find the "Rules" button. Click on it to start creating a new rule.
Use Swimm AI to generate rules: see this page.
Choose the relevant document: This document will be linked with your regex rule and will be displayed whenever the rule's conditions are met in the code.
Enter rule details:
- Title - will be shown in the
Rulesview to identify this rule.
- Description - will be shown when the user hovers over the marked code.
- Regex - the regex that should be met for the rule to apply.
Below, you can see the information filled for the rule
AsyncCache. This is what it looks like when this rule is triggered:
Save, test and commit
Save and test: Click
Apply, and you will be able to see the highlighting in your code. We recommend testing in your IDE to see that the rule works the way you expect.
Commit: Rules are stored in your code under the
.swm/rules.json file. Commit and push your changes to this file. Once your colleagues pull the latest version which includes your changes, everyone will share the same rules.
Developing software often requires understanding complex codebases, adhering to strict coding conventions, navigating the nuances of deprecated code, and interfacing with third-party libraries. Keeping track of all this can be a challenging task for any developer. This is where documentation rules come into play.
These rules serve as proactive guides, highlighting key aspects of the codebase and making relevant documentation readily available to developers.
In this section, we'll walk through a variety of use cases that demonstrate the power of these document hooks. Each use case showcases how these rules can streamline your workflow, make codebases more navigable, and ultimately improve the overall development process.
Example use cases:
1. Enforcing best practices and coding standards
Every team has its coding standards and conventions. Doc rules can highlight these standards directly in the code, ensuring that all team members follow them.
A simple example is using
camelCase for variable naming, a doc rule could catch instances where a developer uses
snake_case and trigger a link to the team's style guide.
2. Handling deprecated code
Over time, certain functions or features may become deprecated. Doc rules can identify these instances and provide developers with a link to the documentation that explains the refactoring project that caused the deprecation and suggests a newer approach or function.
For example, a function called
oldFunction() has been deprecated and replaced by
newFunction(). A doc rule can highlight every instance of
oldFunction() in the code and provide a link to the documentation describing the new function.
3. Working with third-party libraries
When working with third-party libraries, developers may not be familiar with all the best practices or potential pitfalls. Doc rules can identify when certain libraries or APIs are used and provide developers with links to the relevant guides or tutorials.
For instance, a developer uses the
axios.get() function from the
axios library. A doc rule can highlight this line of code and provide a link to an internal doc that guides how to use
axios in their codebase.
4. New features or techniques
When a team introduces a new feature or coding technique, it can be difficult for all developers to understand and adopt it immediately. Doc rules can identify code related to this new feature or technique and provide developers with links to detailed explanations or tutorials.
For instance, a developer starts using a new element from the company's infrastructure called
AsyncCache. Doc rules can prompt the developer to see the relevant documentation.
By using dock rules to hook documentation directly in the code, Swimm can enhance developers' understanding, enforce best practices, keep the codebase up to date, and assist in using third-party libraries effectively.
Where are the rules stored?
In your repository, under the
Can I use AI to generate rules? Yes, see this page.
This document is automatically kept up to date using Swimm.