Skip to content
Thoth Tech

Peer Review Guide

Introduction on how to do a peer review within the SplashKit Web Dev Team

In SplashKit, peer reviews are a vital process to ensure code quality, maintainability, and consistency across the website development project. Every pull request (PR) must follow the Peer-Review Checklist, which checks for key factors like functionality, code readability, and documentation.

Additionally, the Peer-Review Prompts serve as a conversation starter for reviewers, encouraging collaboration while allowing for a thorough and constructive review process.

SplashKit Peer-Review Checklist

The following checklist is required to be completed for every review to ensure high-quality contributions.

## General Information


- [ ] Type of Change: Clearly indicate the type of change (choose one):
  - [ ] Bug fix
  - [ ] New feature
  - [ ] Breaking change
  - [ ] Documentation update


## Code Quality


- [ ] Repository: Ensure the PR is made to the correct repository.
- [ ] Readability: Is the code easy to read and follow? Are comments included where necessary?
- [ ] Maintainability: Can this code be maintained or extended easily in the future?


## Functionality


- [ ] Correctness: Does the code meet the task requirements?
- [ ] Existing Functionality: Has the impact on existing functionality been considered and tested?


## Testing


- [ ] Test Coverage: Are unit tests provided for new or modified code?
- [ ] Test Results: Have all tests passed successfully?


## Documentation


- [ ] Documentation: Is the inline and external documentation updated and clear?


## Pull Request Details


- [ ] PR Description: Is the problem being solved clearly described?
- [ ] Checklist Completion: Have all relevant checklist items been reviewed and completed?

SplashKit Peer-Review Prompts

These prompts can help guide discussions during the review process and ensure that the code meets high standards.

  • Type of Change: Is the PR correctly identifying the type of change (bug fix, new feature, etc.)?
  • Code Readability: Is the code well-structured and easy to follow? Could better comments, names, or organisation improve it?
  • Maintainability: Is the code modular and easy to maintain? Does it introduce any technical debt?
  • Code Simplicity: Are there redundant or overly complex parts of the code that could be simplified?
  • Edge Cases: Does the code account for edge cases? What scenarios might cause it to break?
  • Test Thoroughness: Does the testing cover all edge cases and failure paths? Are there enough tests to ensure code reliability?
  • Backward Compatibility: Does the change break any existing functionality? If so, is backward compatibility handled or documented?
  • Performance Considerations: Could this code impact performance negatively? Can it be optimised while maintaining readability?
  • Security Concerns: Does this change introduce any security risks? Is input validation handled properly?
  • Dependencies: Are new dependencies necessary? Could they conflict with existing libraries? Could this functionality be achieved without new dependencies?
  • Documentation: Is the documentation clear and thorough enough for new developers to understand? Does it cover API or external interface changes?

Review Guidelines for Specific File Types

Different file types require different levels of attention during the review process. Here’s what to look for when reviewing each type of file:

.mdx Files

  • Content Accuracy: Ensure that the content is clear and accurate. Double-check for any errors in the documentation or guides.
  • Frontmatter: Ensure the frontmatter (title, description, etc.) is correctly filled out.
  • Component Usage: Verify that components such as LinkCard, CardGrid, or others are being used appropriately within the .mdx files.

.css Files

  • Consistency: Check that the styles align with the Styling Guide and maintain a consistent use of variables (e.g., colours, fonts, spacing).
  • Accessibility: Review for accessibility considerations, such as whether animations are disabled for users who prefer reduced motion, and whether contrast ratios meet WCAG 2.1 AA standards.
  • Naming Conventions: Ensure that CSS class names follow a consistent naming pattern.

.jsx/.tsx Files

  • Functionality: Make sure the interactive components (e.g., sliders, forms) work as expected and meet the requirements of the task.
  • Performance: Look for unnecessary re-renders or other performance concerns.
  • Code Style: Ensure the code follows React/JSX best practices and any project-specific linting rules.

.astro Files

  • Structure: Ensure the page or component is well-structured and follows the Astro standards for component and page creation.
  • Reusability: Look for opportunities to refactor repetitive code into reusable components.

Useful Resources for Reviewers

By following these guidelines, you’ll ensure that the SplashKit website project maintains high standards of code quality, performance, and accessibility. Remember, peer reviews are not only about verifying the code but also about learning and improving together as a team.