Skip to main content

Doc Rules

Overview​

Swimm's 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 visibility​

Rules appear on a regex match. That applies to existing code and as-you-type code.



info

In JetBrains, there might be a lag until the code highlighting appears under the matching code.

Creating rules​

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 Rules view 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​

  1. 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. Open a file and type to match the Regex pattern you defined. You should see the Rule match with the text you typed. If it doesn't, you may need to adjust the Regex pattern.

  2. 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.

Use cases​

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.

Regex Example: [a-z]+_[a-z]+

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.

Regex Example: oldFunction\s*\(.*\)

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.

Regex Example: axios\.get\s*\(.*\)

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.

Regex Example: \bAsyncCache\b

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.

FAQ​

Where are the rules stored? In your repository, under the .swm/rules.json file.

Can I use AI to generate rules? Yes, see this page.

This document is automatically kept up to date using Swimm.