Table of Contents
Overview
Pointing out coding style and rule violations in code reviews is repetitive and mechanical work. By delegating these checks to tools, we can reduce code review time and allow reviewers to focus on essential issues like functionality and logic.
Currently, a significant amount of time is spent on coding style feedback and corrections during code reviews. By automating the checks for coding rules that the team has agreed upon, we can streamline the code review process. Let’s explore how to achieve this.
Pros and Cons of Unified Code Style
While skipping coding style checks in code reviews would reduce review time, there are many advantages to unifying code style. Let’s look at the pros and cons.
Pros
Improved Code Readability
Developers spend far more time reading and understanding existing code than writing new code.
- Robert C. Martin (“Clean Code”): Developers spend only 10% of their working time writing new code, and 90% reading and understanding existing code.
- Camille Fournier (Software Engineering at Scale): Developers spend 3 times more time reading code than writing it.
- IEEE and ACM research: Improved code readability significantly enhances development speed and maintenance efficiency.
When code style is unified, the time spent reading and understanding existing code decreases, improving overall development productivity.
Improved Maintenance Efficiency
- Time spent understanding existing code decreases when adding or modifying code.
- Reduces confusion during debugging and refactoring, enabling more efficient work.
Enhanced Collaboration
- Unified code style across team members reduces code review time and improves productivity.
- Reduces time spent discussing code style, allowing focus on functional and logical issues.
Reduced Onboarding Time
- New members can understand the project’s codebase and start contributing faster.
- Learning costs are reduced.
Fewer Errors
- Developing with a unified code style reduces mistakes during writing, leading to fewer bugs.
Cons
High Initial Adoption Cost
- Style guides need to be created and existing code may need to be refactored to unify code style.
- Time is required to set up and apply Linter and Formatter tools, which may temporarily reduce productivity.
Time-Consuming Rule Agreement
- It takes time to decide which style to adopt.
- Finding a style that satisfies all members is difficult, and discussions can be lengthy.
Reduced Creativity and Flexibility
- Strict style guides can limit individual coding styles.
- Developers may find it difficult to try their own efficient approaches.
Compatibility Issues with Existing Code
- If there is a large amount of existing code, it may conflict with the new style guide, resulting in two styles coexisting in the codebase.
- Additional time is needed to modify existing code.
Linter/Formatter Overhead
- Multiple errors from Linters or Formatters may take time to fix.
- Linter and Formatter execution time adds overhead.
Code Review Automation Tools
By using tools like Linters to check coding styles and rules in code reviews, we can achieve code review automation. Here are the representative tools.
- ESLint: A syntax and style checking tool for JavaScript/TypeScript code
- Official docs: https://eslint.org/
- Stylelint: A syntax and style checking tool for CSS/SCSS stylesheets
- Semgrep: A static analysis tool that can check code with custom rules based on regular expressions
For reference, Google also maintains style guide documents and tools.
Adding ESLint and Stylelint Rules
If there are coding rules that can be checked by a Linter, it’s recommended to add Linter rules to automate the checks. For more details on adding Linter rules, please refer to the following blog posts.
ESLint rule examples:
Stylelint rule examples:
What is Semgrep
Semgrep is a static analysis tool for automatically checking and improving code security, quality, and style. It is primarily used to analyze source code to find security vulnerabilities, bugs, and code quality issues.
Semgrep allows you to write custom rules using regular expressions, enabling checks on areas that are difficult to inspect with Linters.
For example, if a comment has a - without a description, Linters cannot detect this, but Semgrep can.
Incorrect example:
/**
* Add two numbers
* @param {number} a - number for addition
* @param {number} b -
* @returns {number}
*/For installation and usage of Semgrep, please refer to the following blog post.
Process for Adding Coding Rules
To effectively operate code review automation, it is important to establish a process for adding coding rules. Here is the process.
1. Review Coding Rules
When there is something you want to unify as a coding style or rule during code reviews, create a ticket, share it within the team, and review whether to make it a rule.
2. Add to Coding Rules
Document the decided rule in the coding rules document.
3. Check if Linter Rules Can Be Added
Once a rule is decided, first check if it can be detected by a Linter (ESLint, Stylelint, etc.). If it can, add the rule.
To automatically run Linters on Git commits, you can use Git Hooks tools.
4. Check if Semgrep Rules Can Be Added
For coding rules that cannot be checked by Linter rules, add Semgrep rules for those that can be detected using regular expressions.
5. Add Links to Coding Rules
Add links to the automated check tool rules in the coding rules document. While it may not be necessary to document rules that can be automatically checked, keeping them documented like Google’s style guide is also a good approach.
Semgrep Usage Example
Here is an example of a Semgrep rule that checks for missing parameter descriptions in comments.
rules:
- id: missing-param-description
severity: ERROR
message: 【Comment error】 Please add a correct comment or remove the `-` character.
languages:
- javascript
- typescript
patterns:
- pattern-regex: \*\s*@.*-\s*(\n|\r\n|$)This rule checks for the following cases.
Incorrect example:
An error occurs when there is no description after - in a comment.
/**
* Add two numbers
* @param {number} a - number for addition
* @param {number} b -
* @returns {number}
*/Correct example:
No error occurs when all comments are properly written.
/**
* Add two numbers
* @param {number} a - number for addition
* @param {number} b - number for addition
* @returns {number}
*/Conclusion
In this blog post, we explored how to reduce code review time by automating coding style and rule checks using tools.
While unifying code style has downsides such as initial adoption costs and time spent on rule agreement, in the long run, it offers many advantages including improved code readability, maintenance efficiency, and collaboration.
By utilizing Linters like ESLint and Stylelint along with Semgrep, you can automatically check coding style issues that are repeatedly pointed out in code reviews. Establishing a process for adding coding rules — delegating what Linters can check to Linters, and what they can’t to Semgrep — is effective.
If you’re spending time on repetitive style feedback in code reviews, consider automating with tools.
For a concrete example of adding ESLint rules, please refer to the following blog post.
Was my blog helpful? Please leave a comment at the bottom. it will be a great help to me!
App promotion
Deku.Deku created the applications with Flutter.If you have interested, please try to download them for free.
