Docs: code reviews

src/content/docs/development/code_reviews.md

@@ -0,0 +1,50 @@
+---
+title: Code Reviews
+description: Code reviews best practices
+---
+
+Code reviews are an integral part of any high-quality software development workflow. Whether you're a reviewer or an author, following good practices will improve the team's productivity and code quality while ensuring a smoother development flow.
+Writing clean and readable code, preparing code for review, conducting thorough and effective code reviews, and using tools to automate parts of the process, are key points to keep a healthy codebase.
+
+## Consider the review when writing code
+
+When writing code it is essential to consider the review process right from the start. Code that’s designed with the reviewer in mind results in more efficient and productive code reviews, ultimately speeding up the development lifecycle.
+
+- Prioritize Clean and Readable Code: Adopting consistent coding styles and best practices helps to ensure that everyone on the team can easily understand and maintain each other's code. It also streamlines onboarding for new team members and enhances collaboration across the board.
+- Keep PRs small and focused: Small PRs reduce review complexity, allow for faster feedback, and prevent blockers from piling up in the review pipeline.
+- Incorporate review time in planning: The time it takes for your code to be reviewed, feedback to be incorporated, and any revisions to be made can have a huge impact on a task's overall timeline. Accurately accounting for this in your task estimations ensures more realistic deadlines and helps prevent bottlenecks.
+
+## Preparing Code for Review
+
+As an author, preparing for code review doesn’t only mean writing clean and maintainable code, but also providing context for reviewers to quickly understand what your code is doing.
+Writing clear and comprehensive commit messages and adding relevant documentation and comments is particularly helpful when dealing with complex logic, as it gives reviewers additional insight and helps them follow your thought process.
+
+## Conducting Effective Code Reviews
+
+Effective code reviews require a balance between attention to detail and a focus on the bigger picture. Making sure that we allocate enough time to review a pull request is critical to avoid missing anything.
+
+Understanding the purpose of the code change helps you evaluate whether the implementation truly aligns with the intended functionality, and the proposed solution fits within the larger architecture.
+
+From there, focus on the clarity, maintainability, and correctness of the code, verifying that it meets the team’s coding standards and best practices.
+When any feedback is to be provided, this one should be both actionable and considerate, fostering collaboration rather than discouragement.
+
+## Collaboration and Communication
+
+Good collaboration in code reviews starts before the code is written by anticipating complex changes or implementations and engaging the team in discussions early in the process. By aligning on the approach upfront, reviews become smoother and more efficient.
+
+The actual code review also goes beyond pointing out errors; it requires open communication and empathy. When providing feedback, focus on constructive and actionable comments that help the author understand the problem and how to address it.
+
+## Tools and Automation in Code Reviews
+
+Automation plays a key role in making code reviews more efficient and consistent. By integrating linters and static analysis tools, teams can enforce coding standards and catch errors automatically, allowing reviewers to focus more on logic and architecture.
+
+At Very Good Ventures we use our open source analysis tool, very_good_analysis. Very good analysis is a lint library heavily inspired by flutter_lints and pedantic (although it is deprecated now), but has a stricter set of lint rules. We believe these linting rules create a healthier, more scalable codebase.
+
+## Post-Review: Merging and Follow-Up
+
+Once the code review is complete, it’s important to make sure that all feedback has been properly addressed before merging. When merging, consider best practices like squashing commits to keep the history clean and concise.
+After merging, it’s helpful to follow up on any potential improvements or edge cases identified during the review, ensuring they are tracked and revisited in future iterations.
+
+## Conclusion
+
+Effective code reviews are essential for maintaining a high-quality, maintainable codebase while fostering a collaborative and efficient development process. By prioritizing clear communication, leveraging tools to automate mundane checks, and focusing on collaboration, teams can ensure a smoother, more effective development workflow.