From 895a67a37e7f60c52e0f8dafc75213fb7bdc9785 Mon Sep 17 00:00:00 2001 From: Josh Nelson Date: Fri, 17 Nov 2023 08:40:03 -0700 Subject: [PATCH 01/12] initial content additions: New content for review effectiveness including a sample agenda and sample Outlook meeting template. Updated Readme content to reflect newly added review content. --- docs/code-reviews/README.md | 14 ++++++-- .../resources/meeting-template.oft | 19 ++++++++++ docs/code-reviews/review-effectiveness.md | 33 +++++++++++++++++ docs/code-reviews/sample-agenda.md | 35 +++++++++++++++++++ 4 files changed, 98 insertions(+), 3 deletions(-) create mode 100644 docs/code-reviews/resources/meeting-template.oft create mode 100644 docs/code-reviews/review-effectiveness.md create mode 100644 docs/code-reviews/sample-agenda.md diff --git a/docs/code-reviews/README.md b/docs/code-reviews/README.md index 7bbd065770..a1c7b2cc3c 100644 --- a/docs/code-reviews/README.md +++ b/docs/code-reviews/README.md @@ -1,6 +1,6 @@ # Code Reviews -Developers working on projects should conduct peer code reviews on every pull request (or check-in to a shared branch). +Code reviews are an essential part of the software development process, offering numerous benefits such as improved code quality, shared knowledge, and early bug detection. However, the effectiveness of these reviews largely depends on the approach and mindset of the participants. ## Goals @@ -10,8 +10,16 @@ Code review is a way to have a conversation about the code where participants wi - **Learn and grow** by having others review the code, we get exposed to unfamiliar design patterns or languages among other topics, and even break some bad habits. - **Shared understanding** between the developers over the project's code. +## When do I conduct a code review? + +Developers working on projects should conduct peer code reviews on every pull request (or check-in to a shared branch). + +## How do I make code reviews effective? + +Take a quick peek at [how to maximize the effectiveness of code reviews](review-effectiveness.md). + ## Resources + - [Code review tools](tools.md) -- [Google's Engineering Practices documentation: How to do a code review](https://google.github.io/eng-practices/review/reviewer/) -- [Best Kept Secrets of Peer Code Review](https://static1.smartbear.co/smartbear/media/pdfs/best-kept-secrets-of-peer-code-review_redirected.pdf) +- [Maximizing the effectiveness of code reviews](review-effectiveness.md) \ No newline at end of file diff --git a/docs/code-reviews/resources/meeting-template.oft b/docs/code-reviews/resources/meeting-template.oft new file mode 100644 index 0000000000..f179c06f36 --- /dev/null +++ b/docs/code-reviews/resources/meeting-template.oft @@ -0,0 +1,19 @@ +Hello [TEAM], + +I would like to conduct a code review on [PR #/Description/link]. + +Your homework before the review is to spend a short amount of time reviewing the PR. + +Our Agenda for the review is as follows: + +Overview of the change +Walkthrough of code changes +Review and Discussion +Action Item generation +Wrap-up and Follow-up + +I’m looking forward to great collaboration and feedback! + +Thank you + +[AUTHOR] \ No newline at end of file diff --git a/docs/code-reviews/review-effectiveness.md b/docs/code-reviews/review-effectiveness.md new file mode 100644 index 0000000000..b079f2be3e --- /dev/null +++ b/docs/code-reviews/review-effectiveness.md @@ -0,0 +1,33 @@ +# Maximizing the Effectiveness of Code Reviews + +Code reviews play a crucial role in software development, providing significant advantages including enhanced code quality, knowledge sharing, and the early identification of bugs. The success of these reviews, however, is greatly influenced by the **attitudes** and **methods** adopted by those participating. Key elements that make code reviews more productive and positive experiences for everyone involved follow: + +## Preparation is Key +The success of a code review begins long before the actual meeting. Reviewers should familiarize themselves with the code in advance, while authors need to provide context and objectives. This preparation ensures that the review session focuses on constructive feedback rather than basic understanding. + +## Embracing a Collaborative Mindset +A collaborative approach is vital. Participants should see code reviews as a team effort to enhance the overall project, not as a critique of an individual’s work. Openness to feedback, respectful communication, and a willingness to learn are paramount. Remember, it’s about improving the code, not judging the coder. + +## The Importance of Effective Communication +How feedback is given and received can make or break a code review session. Feedback should be specific, constructive, and focused on the code, not the person who wrote it. Clear and respectful communication fosters a positive environment and encourages learning and growth. + +## Quality Over Ego +Keeping the focus on the quality of the final product helps in setting aside personal preferences and ego. The primary goal is to enhance the code's readability, maintainability, and functionality. + +## The Review Process +A typical code review involves an overview by the author, a thorough walkthrough of the changes, discussions, and the compilation of action items. It's crucial to be detail-oriented but also keep the big picture in mind, ensuring that the code aligns with the project's overall direction. + +## Post-Review Actions +After the review, authors should act on the feedback, refining and improving the code. Follow-up reviews might be necessary for significant changes, ensuring continuous improvement and adherence to project standards. + +## Conclusion +Effective code reviews are not just about catching errors; they are opportunities for team growth and learning. By preparing adequately, fostering a collaborative and respectful environment, focusing on constructive feedback, and prioritizing the project's quality, teams can make the most out of these sessions, leading to robust, efficient, and maintainable software. + +## Encourage Participation and Continuous Improvement +Lastly, remember that code reviews are a continuous learning process. Encourage all team members to participate, share their knowledge, and view each session as an opportunity to improve both the code and their own skills. With the right mindset and approach, code reviews can be a valuable asset in any software development project. + +## Resources + + +- [Further reading: Google's Engineering Practices documentation - How to do a code review](https://google.github.io/eng-practices/review/reviewer/) +- [Best Kept Secrets of Peer Code Review](https://static1.smartbear.co/smartbear/media/pdfs/best-kept-secrets-of-peer-code-review_redirected.pdf) \ No newline at end of file diff --git a/docs/code-reviews/sample-agenda.md b/docs/code-reviews/sample-agenda.md new file mode 100644 index 0000000000..8b008d43de --- /dev/null +++ b/docs/code-reviews/sample-agenda.md @@ -0,0 +1,35 @@ +### Sample code review session outline: + +1. **Preparation** + - Reviewers familiarize themselves with the code changes before the meeting. + - The author of the code provides context and objectives of the changes. + +2. **Overview by Author** + - Brief presentation by the author explaining the main changes, the rationale behind them, and any specific areas where feedback is sought. + +3. **Walkthrough of Code Changes** + - Go through the code changes file by file or feature by feature. + - The author can highlight key areas and explain the logic or approach used. + +4. **Review and Discussion** + - Reviewers provide feedback on various aspects such as design, coding standards, potential bugs, optimization opportunities, and readability. + - Discussion of alternative approaches or solutions where applicable. + - If the team is large, consider focusing on more significant issues to keep the session efficient. + +5. **Action Items** + - Compile a list of action items and areas for improvement identified during the review. + - Assign responsibilities for addressing each item. + +6. **Wrap-up and Follow-up** + - Summarize the session and thank participants for their contributions. + - Schedule any necessary follow-up meetings or reviews for major revisions. + +7. **Post-Session** + - The author addresses the feedback and makes necessary changes. + - Optional: A follow-up review for major changes. + +This structure ensures a thorough, collaborative, and productive code review session. + +## Resources + +- [Meeting Template](resources/meeting-template.md) \ No newline at end of file From fdbbfae84b5adaabe2719df7c4ee35cd5b56b089 Mon Sep 17 00:00:00 2001 From: Josh Nelson Date: Fri, 17 Nov 2023 08:44:53 -0700 Subject: [PATCH 02/12] updated links added sample agenda md link to readme fixed link to agenda oft in sample agenda --- docs/code-reviews/README.md | 2 +- docs/code-reviews/sample-agenda.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/code-reviews/README.md b/docs/code-reviews/README.md index a1c7b2cc3c..bead914669 100644 --- a/docs/code-reviews/README.md +++ b/docs/code-reviews/README.md @@ -20,6 +20,6 @@ Take a quick peek at [how to maximize the effectiveness of code reviews](review- ## Resources - +- [Sample code review session agenda](sample-agenda.md) - [Code review tools](tools.md) - [Maximizing the effectiveness of code reviews](review-effectiveness.md) \ No newline at end of file diff --git a/docs/code-reviews/sample-agenda.md b/docs/code-reviews/sample-agenda.md index 8b008d43de..8511acc9c9 100644 --- a/docs/code-reviews/sample-agenda.md +++ b/docs/code-reviews/sample-agenda.md @@ -32,4 +32,4 @@ This structure ensures a thorough, collaborative, and productive code review ses ## Resources -- [Meeting Template](resources/meeting-template.md) \ No newline at end of file +- [Meeting Template](resources/meeting-template.oft) \ No newline at end of file From c2f093309bd34ee4c2226815f06a9faacff8a0e4 Mon Sep 17 00:00:00 2001 From: Josh Nelson Date: Fri, 17 Nov 2023 08:50:44 -0700 Subject: [PATCH 03/12] updated agenda email template file type Changed from OFT to TXT file type Updated file path reference links --- .../resources/{meeting-template.oft => meeting-template.txt} | 3 +++ docs/code-reviews/sample-agenda.md | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) rename docs/code-reviews/resources/{meeting-template.oft => meeting-template.txt} (89%) diff --git a/docs/code-reviews/resources/meeting-template.oft b/docs/code-reviews/resources/meeting-template.txt similarity index 89% rename from docs/code-reviews/resources/meeting-template.oft rename to docs/code-reviews/resources/meeting-template.txt index f179c06f36..ea56257f85 100644 --- a/docs/code-reviews/resources/meeting-template.oft +++ b/docs/code-reviews/resources/meeting-template.txt @@ -1,3 +1,6 @@ +SUBJECT: Code Review [PR#/Description] + + Hello [TEAM], I would like to conduct a code review on [PR #/Description/link]. diff --git a/docs/code-reviews/sample-agenda.md b/docs/code-reviews/sample-agenda.md index 8511acc9c9..e0b1486f0f 100644 --- a/docs/code-reviews/sample-agenda.md +++ b/docs/code-reviews/sample-agenda.md @@ -32,4 +32,4 @@ This structure ensures a thorough, collaborative, and productive code review ses ## Resources -- [Meeting Template](resources/meeting-template.oft) \ No newline at end of file +- [Meeting Template](resources/meeting-template.txt) \ No newline at end of file From adf753c3355e9495060f9c62adda6b03684b1ef8 Mon Sep 17 00:00:00 2001 From: Josh Nelson Date: Fri, 17 Nov 2023 09:09:36 -0700 Subject: [PATCH 04/12] updated content Added details on psychological safety, updated link order in resources --- docs/code-reviews/README.md | 4 ++-- docs/code-reviews/review-effectiveness.md | 15 ++++++++------- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/code-reviews/README.md b/docs/code-reviews/README.md index bead914669..8899936c65 100644 --- a/docs/code-reviews/README.md +++ b/docs/code-reviews/README.md @@ -20,6 +20,6 @@ Take a quick peek at [how to maximize the effectiveness of code reviews](review- ## Resources -- [Sample code review session agenda](sample-agenda.md) - [Code review tools](tools.md) -- [Maximizing the effectiveness of code reviews](review-effectiveness.md) \ No newline at end of file +- [Maximizing the effectiveness of code reviews](review-effectiveness.md) +- [Sample code review session agenda](sample-agenda.md) \ No newline at end of file diff --git a/docs/code-reviews/review-effectiveness.md b/docs/code-reviews/review-effectiveness.md index b079f2be3e..5b5d27573c 100644 --- a/docs/code-reviews/review-effectiveness.md +++ b/docs/code-reviews/review-effectiveness.md @@ -6,16 +6,16 @@ Code reviews play a crucial role in software development, providing significant The success of a code review begins long before the actual meeting. Reviewers should familiarize themselves with the code in advance, while authors need to provide context and objectives. This preparation ensures that the review session focuses on constructive feedback rather than basic understanding. ## Embracing a Collaborative Mindset -A collaborative approach is vital. Participants should see code reviews as a team effort to enhance the overall project, not as a critique of an individual’s work. Openness to feedback, respectful communication, and a willingness to learn are paramount. Remember, it’s about improving the code, not judging the coder. +A collaborative approach is vital. Participants should approach code reviews as a [safe space](https://www.youtube.com/watch?v=IH67P7EMnt0) to collaborate, review, and improve solutions. Reviews are a team effort to enhance the overall project, not as a critique of an individual’s work. Openness to feedback, respectful communication, and a willingness to learn are paramount. Remember, it’s about improving the code, not judging the coder. ## The Importance of Effective Communication How feedback is given and received can make or break a code review session. Feedback should be specific, constructive, and focused on the code, not the person who wrote it. Clear and respectful communication fosters a positive environment and encourages learning and growth. ## Quality Over Ego -Keeping the focus on the quality of the final product helps in setting aside personal preferences and ego. The primary goal is to enhance the code's readability, maintainability, and functionality. +Check your ego at the door. Keeping the focus on the quality of the final product helps in setting aside personal preferences and ego. The primary goal is to enhance the code's readability, maintainability, and functionality. ## The Review Process -A typical code review involves an overview by the author, a thorough walkthrough of the changes, discussions, and the compilation of action items. It's crucial to be detail-oriented but also keep the big picture in mind, ensuring that the code aligns with the project's overall direction. +A typical code review involves an overview by the author, a thorough walkthrough of the changes, discussions, and the compilation of action items. It's crucial to be detail-oriented but also keep the big picture in mind, ensuring that the code aligns with the project's overall direction. For a sample review agenda, see [Sample Code Review Session Agenda](sample-agenda.md). ## Post-Review Actions After the review, authors should act on the feedback, refining and improving the code. Follow-up reviews might be necessary for significant changes, ensuring continuous improvement and adherence to project standards. @@ -23,11 +23,12 @@ After the review, authors should act on the feedback, refining and improving the ## Conclusion Effective code reviews are not just about catching errors; they are opportunities for team growth and learning. By preparing adequately, fostering a collaborative and respectful environment, focusing on constructive feedback, and prioritizing the project's quality, teams can make the most out of these sessions, leading to robust, efficient, and maintainable software. -## Encourage Participation and Continuous Improvement -Lastly, remember that code reviews are a continuous learning process. Encourage all team members to participate, share their knowledge, and view each session as an opportunity to improve both the code and their own skills. With the right mindset and approach, code reviews can be a valuable asset in any software development project. +## Remember... +Code reviews are a continuous learning process. Encourage all team members to participate, share their knowledge, and view each session as an opportunity to improve both the code and their own skills. With the right mindset and approach, code reviews can be a valuable asset in any software development project. ## Resources - +- [Best Kept Secrets of Peer Code Review](https://static1.smartbear.co/smartbear/media/pdfs/best-kept-secrets-of-peer-code-review_redirected.pdf) - [Further reading: Google's Engineering Practices documentation - How to do a code review](https://google.github.io/eng-practices/review/reviewer/) -- [Best Kept Secrets of Peer Code Review](https://static1.smartbear.co/smartbear/media/pdfs/best-kept-secrets-of-peer-code-review_redirected.pdf) \ No newline at end of file +- [Pyschological Safety in Code Reviews](https://www.youtube.com/watch?v=IH67P7EMnt0) +- [Sample code review session agenda](sample-agenda.md) From a7b44ed9a00b759ac865388a51927370d74cb458 Mon Sep 17 00:00:00 2001 From: Josh Nelson Date: Fri, 17 Nov 2023 09:19:49 -0700 Subject: [PATCH 05/12] Added common issues Added new content for common issues discovered during code reviews; Updated Readme content and resource links; Updated sentence structure for review agenda link. --- docs/code-reviews/README.md | 5 +++++ docs/code-reviews/common-issues.md | 25 +++++++++++++++++++++++ docs/code-reviews/review-effectiveness.md | 2 +- 3 files changed, 31 insertions(+), 1 deletion(-) create mode 100644 docs/code-reviews/common-issues.md diff --git a/docs/code-reviews/README.md b/docs/code-reviews/README.md index 8899936c65..7472902867 100644 --- a/docs/code-reviews/README.md +++ b/docs/code-reviews/README.md @@ -18,8 +18,13 @@ Developers working on projects should conduct peer code reviews on every pull re Take a quick peek at [how to maximize the effectiveness of code reviews](review-effectiveness.md). +## What are common issues code reviews catch? + +Though not an exhaustive list, some of the most common issues that code reviews can help catch are described [here](common-issues.md). + ## Resources - [Code review tools](tools.md) +- [Common issues](common-issues.md) - [Maximizing the effectiveness of code reviews](review-effectiveness.md) - [Sample code review session agenda](sample-agenda.md) \ No newline at end of file diff --git a/docs/code-reviews/common-issues.md b/docs/code-reviews/common-issues.md new file mode 100644 index 0000000000..d40b3a21ec --- /dev/null +++ b/docs/code-reviews/common-issues.md @@ -0,0 +1,25 @@ +## Common issues + +Here are some of the most common issues that code reviews can help catch: + +1. **Bugs and Logical Errors**: Detecting bugs or logical mistakes that might not be evident during initial coding or testing. + +2. **Code Standards Violation**: Ensuring the code adheres to established coding standards and conventions for readability and maintainability. + +3. **Performance Issues**: Identifying inefficient code that could lead to performance problems, like slow execution or excessive resource usage. + +4. **Security Vulnerabilities**: Spotting security flaws, such as SQL injections, buffer overflows, or improper handling of user data. + +5. **Code Duplication**: Finding and reducing redundant code, which can make maintenance harder and increase the risk of bugs. + +6. **Lack of Scalability**: Recognizing code that may not scale well with increased load or data volume. + +7. **Poor Error Handling**: Pointing out insufficient or incorrect error handling that could lead to crashes or unpredictable behavior. + +8. **Inadequate or Missing Documentation**: Ensuring that code is well-documented for ease of understanding and future maintenance. + +9. **Compatibility Issues**: Checking for compatibility with different browsers, operating systems, or hardware, especially in web and mobile app development. + +10. **Design Flaws**: Identifying flaws in the software design, like tightly coupled components or violation of SOLID principles, which can affect flexibility and testability. + +Addressing these issues during the review process significantly improves the quality and reliability of the software. \ No newline at end of file diff --git a/docs/code-reviews/review-effectiveness.md b/docs/code-reviews/review-effectiveness.md index 5b5d27573c..91434f47ca 100644 --- a/docs/code-reviews/review-effectiveness.md +++ b/docs/code-reviews/review-effectiveness.md @@ -15,7 +15,7 @@ How feedback is given and received can make or break a code review session. Feed Check your ego at the door. Keeping the focus on the quality of the final product helps in setting aside personal preferences and ego. The primary goal is to enhance the code's readability, maintainability, and functionality. ## The Review Process -A typical code review involves an overview by the author, a thorough walkthrough of the changes, discussions, and the compilation of action items. It's crucial to be detail-oriented but also keep the big picture in mind, ensuring that the code aligns with the project's overall direction. For a sample review agenda, see [Sample Code Review Session Agenda](sample-agenda.md). +A typical code review involves an overview by the author, a thorough walkthrough of the changes, discussions, and the compilation of action items. It's crucial to be detail-oriented but also keep the big picture in mind, ensuring that the code aligns with the project's overall direction. See [Sample Code Review Session Agenda](sample-agenda.md). ## Post-Review Actions After the review, authors should act on the feedback, refining and improving the code. Follow-up reviews might be necessary for significant changes, ensuring continuous improvement and adherence to project standards. From 981d736ffa998c8f34e975a52a958ab0e6c20a48 Mon Sep 17 00:00:00 2001 From: Josh Nelson Date: Fri, 17 Nov 2023 09:39:12 -0700 Subject: [PATCH 06/12] Added reference to SOLID principles further details --- .../design/design-patterns/code-principles.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 docs/design/design-patterns/code-principles.md diff --git a/docs/design/design-patterns/code-principles.md b/docs/design/design-patterns/code-principles.md new file mode 100644 index 0000000000..2d911516be --- /dev/null +++ b/docs/design/design-patterns/code-principles.md @@ -0,0 +1,25 @@ +# Code Principles + +In software development, "code principles" refer to a set of guidelines or best practices that aim to improve the quality of code, make it more maintainable, and facilitate collaboration among developers. Some of the most well-known and widely adopted principles: + +**DRY (Don't Repeat Yourself)**: This principle advocates for reducing repetition of software patterns. Instead of having duplicate code, it suggests using abstractions or data normalization to avoid redundancy, which makes the code easier to maintain and update. + +**KISS (Keep It Simple, Stupid)**: KISS emphasizes simplicity in design. It suggests that systems work better if they are kept simple rather than made complex. Simplicity should be a key goal in design, and unnecessary complexity should be avoided. + +**YAGNI (You Ain't Gonna Need It)**: This principle is a reminder to developers not to add functionality until it is necessary. It encourages programmers to avoid implementing features or code that are not currently needed, on the expectation that they will be needed in the future. + +**SOLID Principles**: This is a collection of five principles (Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion) that guide object-oriented design and programming for more scalable, maintainable, and robust systems. Further details can be found [here](https://www.digitalocean.com/community/conceptual_articles/s-o-l-i-d-the-first-five-principles-of-object-oriented-design). + +**Clean Code Principles**: These are guidelines for writing code that is easy to read, understand, and modify. They involve using meaningful names, writing small functions, keeping code units simple, and writing code that expresses the intent clearly. + +**Boy Scout Rule**: The idea is to always leave the code you're working on a little better than you found it. By continuously improving the codebase, even in small ways, the overall quality of the software improves over time. + +**Principle of Least Astonishment (POLA/POLS)**: This principle suggests that a component of a system should behave in a way that is least surprising to users. It implies that the functionality should meet the expectations of those who use it. + +**Fail Fast**: The concept here is to enable systems to fail quickly when an issue arises, rather than attempting to proceed in an unstable state. This approach helps in identifying problems early and simplifying the debugging process. + +**Law of Demeter (LoD)**: Also known as the principle of least knowledge, this principle suggests that a module should know as little as possible about the internal workings of other modules. It is aimed at reducing dependencies between parts of a system. + +**Principle of Single Source of Truth (SSOT)**: This principle states that every piece of knowledge or data should only be stored in one place. This avoids the problems of data duplication and inconsistency. + +These principles are not hard-and-fast rules but rather guidelines that help developers write better, more efficient, and more maintainable code. They are particularly useful in collaborative environments and large-scale software projects. \ No newline at end of file From 481582aef1684c6f23cdaaac58c0d448ca6ca74c Mon Sep 17 00:00:00 2001 From: Josh Nelson Date: Fri, 17 Nov 2023 09:42:11 -0700 Subject: [PATCH 07/12] removed non-related PR content --- docs/code-reviews/common-issues.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/code-reviews/common-issues.md b/docs/code-reviews/common-issues.md index d40b3a21ec..7de60a8254 100644 --- a/docs/code-reviews/common-issues.md +++ b/docs/code-reviews/common-issues.md @@ -20,6 +20,10 @@ Here are some of the most common issues that code reviews can help catch: 9. **Compatibility Issues**: Checking for compatibility with different browsers, operating systems, or hardware, especially in web and mobile app development. -10. **Design Flaws**: Identifying flaws in the software design, like tightly coupled components or violation of SOLID principles, which can affect flexibility and testability. +10. **Design Flaws**: Identifying flaws in the software design, like tightly coupled components or violation of [SOLID principles](https://www.digitalocean.com/community/conceptual_articles/s-o-l-i-d-the-first-five-principles-of-object-oriented-design), which can affect flexibility and testability. -Addressing these issues during the review process significantly improves the quality and reliability of the software. \ No newline at end of file +Addressing these issues during the review process significantly improves the quality and reliability of the software. + +## Resources + +- [SOLID Principles](https://www.digitalocean.com/community/conceptual_articles/s-o-l-i-d-the-first-five-principles-of-object-oriented-design) \ No newline at end of file From 835b22f297836b6e80e30cfeca0b9514f42807c9 Mon Sep 17 00:00:00 2001 From: Josh Nelson Date: Fri, 17 Nov 2023 09:42:44 -0700 Subject: [PATCH 08/12] removed non-related PR content --- .../design/design-patterns/code-principles.md | 25 ------------------- 1 file changed, 25 deletions(-) delete mode 100644 docs/design/design-patterns/code-principles.md diff --git a/docs/design/design-patterns/code-principles.md b/docs/design/design-patterns/code-principles.md deleted file mode 100644 index 2d911516be..0000000000 --- a/docs/design/design-patterns/code-principles.md +++ /dev/null @@ -1,25 +0,0 @@ -# Code Principles - -In software development, "code principles" refer to a set of guidelines or best practices that aim to improve the quality of code, make it more maintainable, and facilitate collaboration among developers. Some of the most well-known and widely adopted principles: - -**DRY (Don't Repeat Yourself)**: This principle advocates for reducing repetition of software patterns. Instead of having duplicate code, it suggests using abstractions or data normalization to avoid redundancy, which makes the code easier to maintain and update. - -**KISS (Keep It Simple, Stupid)**: KISS emphasizes simplicity in design. It suggests that systems work better if they are kept simple rather than made complex. Simplicity should be a key goal in design, and unnecessary complexity should be avoided. - -**YAGNI (You Ain't Gonna Need It)**: This principle is a reminder to developers not to add functionality until it is necessary. It encourages programmers to avoid implementing features or code that are not currently needed, on the expectation that they will be needed in the future. - -**SOLID Principles**: This is a collection of five principles (Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion) that guide object-oriented design and programming for more scalable, maintainable, and robust systems. Further details can be found [here](https://www.digitalocean.com/community/conceptual_articles/s-o-l-i-d-the-first-five-principles-of-object-oriented-design). - -**Clean Code Principles**: These are guidelines for writing code that is easy to read, understand, and modify. They involve using meaningful names, writing small functions, keeping code units simple, and writing code that expresses the intent clearly. - -**Boy Scout Rule**: The idea is to always leave the code you're working on a little better than you found it. By continuously improving the codebase, even in small ways, the overall quality of the software improves over time. - -**Principle of Least Astonishment (POLA/POLS)**: This principle suggests that a component of a system should behave in a way that is least surprising to users. It implies that the functionality should meet the expectations of those who use it. - -**Fail Fast**: The concept here is to enable systems to fail quickly when an issue arises, rather than attempting to proceed in an unstable state. This approach helps in identifying problems early and simplifying the debugging process. - -**Law of Demeter (LoD)**: Also known as the principle of least knowledge, this principle suggests that a module should know as little as possible about the internal workings of other modules. It is aimed at reducing dependencies between parts of a system. - -**Principle of Single Source of Truth (SSOT)**: This principle states that every piece of knowledge or data should only be stored in one place. This avoids the problems of data duplication and inconsistency. - -These principles are not hard-and-fast rules but rather guidelines that help developers write better, more efficient, and more maintainable code. They are particularly useful in collaborative environments and large-scale software projects. \ No newline at end of file From 66dde056f265710bc9705b2dce98aa37dd39d2d5 Mon Sep 17 00:00:00 2001 From: Josh Nelson Date: Fri, 17 Nov 2023 11:04:19 -0700 Subject: [PATCH 09/12] fixed linter markdown syntax warnings --- docs/code-reviews/common-issues.md | 2 +- docs/code-reviews/review-effectiveness.md | 2 +- docs/code-reviews/sample-agenda.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/code-reviews/common-issues.md b/docs/code-reviews/common-issues.md index 7de60a8254..8b6cf19af0 100644 --- a/docs/code-reviews/common-issues.md +++ b/docs/code-reviews/common-issues.md @@ -1,4 +1,4 @@ -## Common issues +# Common issues Here are some of the most common issues that code reviews can help catch: diff --git a/docs/code-reviews/review-effectiveness.md b/docs/code-reviews/review-effectiveness.md index 91434f47ca..da5b489ef1 100644 --- a/docs/code-reviews/review-effectiveness.md +++ b/docs/code-reviews/review-effectiveness.md @@ -23,7 +23,7 @@ After the review, authors should act on the feedback, refining and improving the ## Conclusion Effective code reviews are not just about catching errors; they are opportunities for team growth and learning. By preparing adequately, fostering a collaborative and respectful environment, focusing on constructive feedback, and prioritizing the project's quality, teams can make the most out of these sessions, leading to robust, efficient, and maintainable software. -## Remember... +## Remember Code reviews are a continuous learning process. Encourage all team members to participate, share their knowledge, and view each session as an opportunity to improve both the code and their own skills. With the right mindset and approach, code reviews can be a valuable asset in any software development project. ## Resources diff --git a/docs/code-reviews/sample-agenda.md b/docs/code-reviews/sample-agenda.md index e0b1486f0f..8262c9db45 100644 --- a/docs/code-reviews/sample-agenda.md +++ b/docs/code-reviews/sample-agenda.md @@ -1,4 +1,4 @@ -### Sample code review session outline: +# Sample code review session outline 1. **Preparation** - Reviewers familiarize themselves with the code changes before the meeting. From 2a0b07d82b3fb06d090f2e5d4f987fb9f5bf4697 Mon Sep 17 00:00:00 2001 From: Josh Nelson Date: Fri, 17 Nov 2023 11:12:19 -0700 Subject: [PATCH 10/12] fixed linter-discovered spelling updated spelling ignore list --- .cspell.json | 2 ++ docs/automated-testing/performance-testing/load-testing.md | 4 ++-- docs/code-reviews/review-effectiveness.md | 2 +- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/.cspell.json b/.cspell.json index a3f26df1f8..8ddbd4c4e0 100644 --- a/.cspell.json +++ b/.cspell.json @@ -182,6 +182,7 @@ "htmlcov", "hyperscale", "Idempotency", + "IMDB", "inclusivelint", "inclusivity", "inferencing", @@ -271,6 +272,7 @@ "netcat", "newarchitecture", "Newtonsoft", + "NGSA", "Nocera", "noninteractive", "NPMJS", diff --git a/docs/automated-testing/performance-testing/load-testing.md b/docs/automated-testing/performance-testing/load-testing.md index efc0dc4c89..b048d9bba0 100644 --- a/docs/automated-testing/performance-testing/load-testing.md +++ b/docs/automated-testing/performance-testing/load-testing.md @@ -60,7 +60,7 @@ Here are a few popular load testing frameworks you may consider, and the languag - **Artillery** () - Write your scenarios in Javascript, executes a node application. - **Gatling** () - Write your scenarios in Scala with their DSL. - **Locust** () - Write your scenarios in Python using the concept of concurrent user activity. -- **K6** () - Write your test scenarios in Javascript, available as open source kubernetes operator, open source Docker image, or as SaaS. Particulary useful for distributed load testing. Integrates easily with prometheus. +- **K6** () - Write your test scenarios in Javascript, available as open source kubernetes operator, open source Docker image, or as SaaS. Particularly useful for distributed load testing. Integrates easily with prometheus. - **NBomber** () - Write your test scenarios in C# or F#, available integration with test runners (NUnit/xUnit). - **WebValidate** () - Web request validation tool used to run end-to-end tests and long-running performance and availability tests. @@ -69,7 +69,7 @@ Here are a few popular load testing frameworks you may consider, and the languag In the case where a specific workload application is not being provided and the focus is instead on the system, here are a few popular sample workload applications you may consider. - **HttpBin** ([Python](https://github.com/postmanlabs/httpbin), [GoLang](https://github.com/mccutchen/go-httpbin)) - Supports variety of endpoint types and language implementations. Can echo data used in request. -- **NGSA** ([Java](https://github.com/retaildevcrews/ngsa-java), [C#](https://github.com/retaildevcrews/ngsa-java)) - Intended for Kubernetes Platform and Monitoring Testing. Built on top of IMDB data store with many CRUD endpoints available. Does not need to have a live database connection. +- **NGSA** ([Java](https://github.com/retaildevcrews/ngsa-java), [C#](https://github.com/retaildevcrews/ngsa-java)) - Intended for Kubernetes Platform and Monitoring Testing. Built on top of an IMDB data store with many CRUD endpoints available. Does not need to have a live database connection. - **MockBin** () - Allows you to generate custom endpoints to test, mock, and track HTTP requests & responses between libraries, sockets and APIs. diff --git a/docs/code-reviews/review-effectiveness.md b/docs/code-reviews/review-effectiveness.md index da5b489ef1..60442dcc10 100644 --- a/docs/code-reviews/review-effectiveness.md +++ b/docs/code-reviews/review-effectiveness.md @@ -30,5 +30,5 @@ Code reviews are a continuous learning process. Encourage all team members to pa - [Best Kept Secrets of Peer Code Review](https://static1.smartbear.co/smartbear/media/pdfs/best-kept-secrets-of-peer-code-review_redirected.pdf) - [Further reading: Google's Engineering Practices documentation - How to do a code review](https://google.github.io/eng-practices/review/reviewer/) -- [Pyschological Safety in Code Reviews](https://www.youtube.com/watch?v=IH67P7EMnt0) +- [Psychological Safety in Code Reviews](https://www.youtube.com/watch?v=IH67P7EMnt0) - [Sample code review session agenda](sample-agenda.md) From 891d9d63a4655386c6d4c97d551b70ec6727f9f2 Mon Sep 17 00:00:00 2001 From: Josh Nelson Date: Fri, 17 Nov 2023 11:30:06 -0700 Subject: [PATCH 11/12] fixed linter 404 links --- docs/automated-testing/fault-injection-testing/README.md | 2 +- docs/code-reviews/pull-requests.md | 2 +- docs/code-reviews/recipes/markdown.md | 2 +- docs/design/design-patterns/rest-api-design-guidance.md | 2 +- docs/observability/tools/KubernetesDashboards.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/automated-testing/fault-injection-testing/README.md b/docs/automated-testing/fault-injection-testing/README.md index 3edf15e2fd..a62c1776ff 100644 --- a/docs/automated-testing/fault-injection-testing/README.md +++ b/docs/automated-testing/fault-injection-testing/README.md @@ -29,7 +29,7 @@ Fault injection methods are a way to increase coverage and validate software rob * **Error** - That part of the system state that may cause a subsequent failure. * **Failure** - An event that occurs when the delivered service deviates from correct state. * **Fault-Error-Failure cycle** - A key mechanism in [dependability](https://en.wikipedia.org/wiki/Dependability): A fault may cause an error. An error may cause further errors within the system boundary; therefore each new error acts as a fault. When error states are observed at the system boundary, they are termed failures. -(Modeled by [Laprie/Avizienis](https://www.nasa.gov/pdf/636745main_day_3-algirdas_avizienis.pdf)) +(Modeled by [Laprie/Avizienis](http://rodin.cs.ncl.ac.uk/Publications/avizienis.pdf)) #### Fault Injection Testing Basics diff --git a/docs/code-reviews/pull-requests.md b/docs/code-reviews/pull-requests.md index a8b1ae5776..87e1e0e22b 100644 --- a/docs/code-reviews/pull-requests.md +++ b/docs/code-reviews/pull-requests.md @@ -88,6 +88,6 @@ See also [Pull Request Template](pull-request-template/pull-request-template.md) * [Google approach to PR size](https://google.github.io/eng-practices/review/developer/small-cls.html) * [Feature Flags](https://www.martinfowler.com/articles/feature-toggles.html) * [Facebook approach to hidden features](https://launchdarkly.com/blog/secret-to-facebooks-hacker-engineering-culture/) -* [Azure approach to canary releases](https://learn.microsoft.com/azure/architecture/framework/devops/release-engineering-cd#stage-your-workloads) +* [Azure approach to canary releases with K8](https://github.com/MicrosoftDocs/azure-pipelines-canary-k8s) * [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0-beta.2/) * [Angular Commit types](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#type) diff --git a/docs/code-reviews/recipes/markdown.md b/docs/code-reviews/recipes/markdown.md index bdd1ae0346..9579479037 100644 --- a/docs/code-reviews/recipes/markdown.md +++ b/docs/code-reviews/recipes/markdown.md @@ -48,7 +48,7 @@ A comprehensive list of markdownlint rules is available [here](https://github.co ### proselint -[`proselint`](http://proselint.com/) is a command line utility that lints the text contents of the document. It checks for jargon, spelling errors, redundancy, corporate speak and other language related issues. +`proselint` is a command line utility that lints the text contents of the document. It checks for jargon, spelling errors, redundancy, corporate speak and other language related issues. It's available both as a [python package](https://github.com/amperser/proselint/#checks) and a [node package](https://www.npmjs.com/package/proselint). diff --git a/docs/design/design-patterns/rest-api-design-guidance.md b/docs/design/design-patterns/rest-api-design-guidance.md index dba5bc8b3b..22c4961063 100644 --- a/docs/design/design-patterns/rest-api-design-guidance.md +++ b/docs/design/design-patterns/rest-api-design-guidance.md @@ -91,6 +91,6 @@ In particular, when working in an existing API ecosystem, be sure to align with * [Detailed HTTP status code definitions](https://www.restapitutorial.com/httpstatuscodes.html) * [Semantic Versioning](https://semver.org/) * [Other Public API Guidelines](http://apistylebook.com/design/guidelines/) -* [OpenAPI Design Practices](https://oai.github.io/Documentation/best-practices.html) +* [OpenAPI Design Practices](https://learn.openapis.org/best-practices.html) * [Microsoft TypeSpec](https://github.com/Microsoft/typespec) * [Microsoft TypeSpec GitHub Workflow samples](https://github.com/cse-labs/typespec-workflow-samples/) diff --git a/docs/observability/tools/KubernetesDashboards.md b/docs/observability/tools/KubernetesDashboards.md index f52a0b52fd..cb6df60000 100644 --- a/docs/observability/tools/KubernetesDashboards.md +++ b/docs/observability/tools/KubernetesDashboards.md @@ -36,4 +36,4 @@ There are currently several UI dashboards available to monitor your applications ## References - [Alternatives to Kubernetes Dashboard](https://octopus.com/blog/alternative-kubernetes-dashboards) -- [Prometheus and Grafana with Kubernetes](https://tanzu.vmware.com/developer/guides/kubernetes/observability-prometheus-grafana-p1/) +- [Prometheus and Grafana with Kubernetes](https://www.youtube.com/watch?v=dk2-_DbWb80) From 2e722b5156a0af647e4bae1b3e1e9a8b01e08189 Mon Sep 17 00:00:00 2001 From: Josh Nelson <11245067+cloudappsguy@users.noreply.github.com> Date: Thu, 30 Nov 2023 09:13:21 -0700 Subject: [PATCH 12/12] Update README.md verbiage change from essential to required per Cook's suggestion. Signed-off-by: Josh Nelson <11245067+cloudappsguy@users.noreply.github.com> --- docs/code-reviews/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/code-reviews/README.md b/docs/code-reviews/README.md index 7472902867..75578296a1 100644 --- a/docs/code-reviews/README.md +++ b/docs/code-reviews/README.md @@ -1,6 +1,6 @@ # Code Reviews -Code reviews are an essential part of the software development process, offering numerous benefits such as improved code quality, shared knowledge, and early bug detection. However, the effectiveness of these reviews largely depends on the approach and mindset of the participants. +Code reviews are a required part of the software development process, offering numerous benefits such as improved code quality, shared knowledge, and early bug detection. However, the effectiveness of these reviews largely depends on the approach and mindset of the participants. ## Goals @@ -27,4 +27,4 @@ Though not an exhaustive list, some of the most common issues that code reviews - [Code review tools](tools.md) - [Common issues](common-issues.md) - [Maximizing the effectiveness of code reviews](review-effectiveness.md) -- [Sample code review session agenda](sample-agenda.md) \ No newline at end of file +- [Sample code review session agenda](sample-agenda.md)