Skip to main content

Code Reviews

This document covers key concepts, guidelines, best practices, examples, tools, and troubleshooting related to reviewing pull requests. It aims to streamline code reviews and foster high-quality, maintainable code.

Key Concepts of Code Reviews​

  • Code Consistency: Ensure the code follows the agreed-upon conventions and standards across the codebase for readability and maintenance.
  • Functionality Verification: Confirm that the code functions as intended, addressing the original requirements without introducing new issues.
  • Readability and Clarity: Prioritize clean, self-explanatory code that is easy to read and understand.
  • Performance Considerations: Ensure the code does not introduce performance regressions and adheres to best practices for efficiency.
  • Scalability: Verify that the code can handle future expansion without significant rework.
  • Feedback Communication: Provide constructive feedback that helps the author improve their code without discouraging them.

1. BEM (Block, Element, Modifier)​

Best Practices​

  • Clear and Consistent Naming: Ensure straightforward names for Blocks, Elements, and Modifiers to facilitate better understanding and code readability.
  • Modular Structure: Break down the user interface into smaller, reusable components, making updates and maintenance more manageable.

Common Pitfalls​

  • Overly Complex Names: Avoid creating long or overly detailed class names, as this can lead to confusion.
  • Excessive Nesting: Keep nesting shallow to prevent complicated and hard-to-maintain CSS selectors.

Example​

<div class="card">
  <div class="card__header">Header</div>
  <div class="card__body">Body</div>
  <div class="card__footer card__footer--highlighted">Footer</div>
</div>

Code Review Checklist for BEM​

  • Are class names clear and consistent?
  • Is there as little nesting as possible, to avoid overly specific selectors?

More about BEM can be found on our BEM page.

2. SASS​

Best Practices​

  • Comment Your Code: Add comments to explain complex logic, aiding future code reviewers.
  • Modular Code Structure: Separate SCSS files by logical concerns to maintain clarity.
  • Meaningful Naming: Choose descriptive names for variables, mixins, and extends.

Common Mistakes​

  • Deep Nesting: Avoid deep nesting to prevent overly specific CSS.
  • Overuse of Mixins and Extends: Limit their use to prevent bloated stylesheets.

Example​

$primary-color: #3498db;

.button {
  color: $primary-color;
  &:hover {
    color: darken($primary-color, 10%);
  }
}

Code Review Checklist for SASS​

  • Are comments added to explain complex logic?
  • Is the nesting level shallow?
  • Are mixins and extends used appropriately without excess?

More about SASS can be found on our SASS page.

3. TypeScript​

Best Practices​

  • Use Type Annotations: Annotate variables and function parameters for early error detection.
  • Use Interfaces and Types: Define object shapes for consistency.

Common Pitfalls​

  • Avoid any Type: Using any defeats the purpose of type safety.
  • Proper Module Imports: Ensure correct module imports to avoid runtime issues.

Example​

let myVar: string = 'Hello, TypeScript';

function greet(name: string): void {
  console.log(`Hello, ${name}`);
}
interface User {
  name: string;
  age: number;
  role: UserRole;
}

type UserRole = AdminRole | DefaultRole;

type AdminRole = 'admin';
type DefaultRole = 'default';

Code Review Checklist for TypeScript​

  • Are type annotations used for variables and function parameters?
  • Are interfaces and types clearly defined and used appropriately?
  • Are module imports correctly formatted?

More about TypeScript can be found on our TypeScript page.

4. Jinja2​

Best Practices​

  • Template Structure: Separate base templates and child templates for a modular and maintainable codebase.
  • Readable Code: Use clear variable names for easier template comprehension.
  • Reusability with Macros: Use macros to create reusable components and simplify your templates.

Common Pitfalls​

  • Excessive Logic in Templates: Keep as little logic as possible in templates. Delegate complex logic to Python scripts.
  • Hardcoding Values: Avoid hardcoding; rely on context variables for flexibility.

Example​

{% extends "base.html" %}
{% block content %}
  <h1>{{ title }}</h1>
  {% for item in items %}
    <p>{{ item.name }}</p>
  {% endfor %}
{% endblock %}

Code Review Checklist for Jinja2​

  • Is the template structure modular and maintainable?
  • Are macros used for reusable components?
  • Is complex logic avoided within templates?