Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: code reviews #56

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

Docs: code reviews #56

wants to merge 8 commits into from

Conversation

B0berman
Copy link

@B0berman B0berman commented Aug 23, 2024

Adding section for code reviews

Copy link
Member

@jsgalarraga jsgalarraga left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a lot of good content here. I proposed some format changes.

Overall I also see this documentation with independent paragraphs rather than with a connected narrative, but not sure how to address it 😅

src/content/docs/development/code_reviews.md Outdated Show resolved Hide resolved
src/content/docs/development/code_reviews.md Outdated Show resolved Hide resolved
src/content/docs/development/code_reviews.md Outdated Show resolved Hide resolved
src/content/docs/development/code_reviews.md Outdated Show resolved Hide resolved
src/content/docs/development/code_reviews.md Outdated Show resolved Hide resolved
src/content/docs/development/code_reviews.md Outdated Show resolved Hide resolved
src/content/docs/development/code_reviews.md Outdated Show resolved Hide resolved
src/content/docs/development/code_reviews.md Outdated Show resolved Hide resolved
@B0berman B0berman requested a review from jolexxa September 17, 2024 12:11
src/content/docs/development/code_reviews.md Outdated Show resolved Hide resolved
src/content/docs/development/code_reviews.md Outdated Show resolved Hide resolved
src/content/docs/development/code_reviews.md Outdated Show resolved Hide resolved
@B0berman B0berman requested a review from jolexxa September 19, 2024 08:43
Copy link
Collaborator

@marwfair marwfair left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is looking great! Just left a couple of small feedback items to improve consistency and readability.


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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Keep the words lower case to stay consistent with the other points.

Suggested change
- 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.
- 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.

## 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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: Split this sentence up to make it more readable.

Suggested change
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.
Writing clear and comprehensive commit messages, along with relevant documentation and comments, is especially valuable when working with complex logic. It provides reviewers with deeper insights and makes it easier for them to understand your thought process.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants