From 6a0b7dcbbac62665ba1bc9a8d3b5058212bda789 Mon Sep 17 00:00:00 2001 From: Marcel Deutzer Date: Sun, 15 Mar 2026 14:01:53 +0100 Subject: [PATCH 1/4] Add OOP design patterns instructions for clean code practices --- docs/README.instructions.md | 1 + .../oop-design-patterns.instructions.md | 78 +++++++++++++++++++ 2 files changed, 79 insertions(+) create mode 100644 instructions/oop-design-patterns.instructions.md diff --git a/docs/README.instructions.md b/docs/README.instructions.md index 671ac8e38..c684e7ae1 100644 --- a/docs/README.instructions.md +++ b/docs/README.instructions.md @@ -84,6 +84,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-instructions) for guidelines on | [Debian Linux Administration Guidelines](../instructions/debian-linux.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdebian-linux.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdebian-linux.instructions.md) | Guidance for Debian-based Linux administration, apt workflows, and Debian policy conventions. | | [Define Events (Preview)](../instructions/pcf-events.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpcf-events.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpcf-events.instructions.md) | Define and handle custom events in PCF components | | [Dependent Libraries (Preview)](../instructions/pcf-dependent-libraries.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpcf-dependent-libraries.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpcf-dependent-libraries.instructions.md) | Using dependent libraries in PCF components | +| [Design Patterns for Object-Oriented Programming for Clean Code](../instructions/oop-design-patterns.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Foop-design-patterns.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Foop-design-patterns.instructions.md) | Best practices for applying Object-Oriented Programming (OOP) design patterns, including Gang of Four (GoF) patterns and SOLID principles | | [Dev Box image definitions](../instructions/devbox-image-definition.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdevbox-image-definition.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdevbox-image-definition.instructions.md) | Authoring recommendations for creating YAML based image definition files for use with Microsoft Dev Box Team Customizations | | [DevOps Core Principles](../instructions/devops-core-principles.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdevops-core-principles.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdevops-core-principles.instructions.md) | Foundational instructions covering core DevOps principles, culture (CALMS), and key metrics (DORA) to guide GitHub Copilot in understanding and promoting effective software delivery. | | [Dotnet Wpf](../instructions/dotnet-wpf.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-wpf.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-wpf.instructions.md) | .NET WPF component and application patterns | diff --git a/instructions/oop-design-patterns.instructions.md b/instructions/oop-design-patterns.instructions.md new file mode 100644 index 000000000..742bb7345 --- /dev/null +++ b/instructions/oop-design-patterns.instructions.md @@ -0,0 +1,78 @@ +--- +description: 'Best practices for applying Object-Oriented Programming (OOP) design patterns, including Gang of Four (GoF) patterns and SOLID principles, to ensure clean, maintainable, and scalable code.' +applyTo: '*' +--- + + +# Design Patterns for Object-Oriented Programming for Clean Code + +These instructions configure GitHub Copilot to prioritize Gang of Four (GoF) Design Patterns, SOLID principles, and clean Object-Oriented Programming (OOP) practices when generating or refactoring code. + +## Core Architectural Philosophy + +- **Program to an Interface, not an Implementation:** Always favor abstract classes or interfaces over concrete implementations. Use dependency injection to provide concrete instances. +- **Favor Object Composition over Class Inheritance:** Use composition to combine behaviors dynamically at runtime. Avoid deep inheritance trees. Use Delegation where appropriate to reuse behavior without breaking encapsulation. +- **Encapsulate What Varies:** Identify the aspects of the application that vary and separate them from what stays the same. Use patterns like Strategy, State, or Bridge to isolate these variations. +- **Loose Coupling:** Minimize direct dependencies between classes. Use Mediator, Observer, or abstract factories to keep components decoupled. + +## Creational Patterns Guidelines + +When generating code that involves object creation or instantiation, apply these patterns to decouple the system from how its objects are created: + +- **Abstract Factory:** Use when a system must be configured with one of multiple families of related products (e.g., cross-platform UI widgets). Ensure clients only interact with the abstract factory and abstract product interfaces. +- **Factory Method:** Use when a class cannot anticipate the class of objects it must create. Defer instantiation to subclasses. +- **Builder:** Use when constructing a complex object requires a step-by-step process, especially when the same construction process can yield different representations. +- **Singleton:** Use *only* when absolutely necessary to guarantee a single instance of a class and provide a global access point (e.g., a central configuration manager or a hardware interface). Prefer Dependency Injection over strict Singletons where possible. +- **Prototype:** Use to avoid building a class hierarchy of factories or when creating an object from scratch is more expensive than cloning an existing one. + +## Structural Patterns Guidelines + +When generating code that defines how classes and objects are composed to form larger structures, apply these patterns: + +- **Adapter:** Use to make incompatible interfaces work together. Prefer Object Adapters (using composition) over Class Adapters (using multiple inheritance) for greater flexibility. +- **Bridge:** Use to separate an abstraction from its implementation so the two can vary independently (e.g., separating a high-level `Window` concept from platform-specific `WindowImpl` logic). +- **Composite:** Use to represent part-whole hierarchies. Ensure clients can treat individual objects and compositions of objects uniformly via a common `Component` interface. +- **Decorator:** Use to attach additional responsibilities to an object dynamically. Prefer this over subclassing for extending functionality to prevent class explosion. Ensure the Decorator has the exact same interface as the component it decorates. +- **Facade:** Use to provide a simple, unified interface to a complex subsystem. +- **Flyweight:** Use to minimize memory usage or computational expenses by sharing as much as possible with similar objects. +- **Proxy:** Use to provide a surrogate or placeholder for another object to control access to it (e.g., lazy loading, access control, or remote communication). + +## Behavioral Patterns Guidelines + +When generating code involving algorithms, control flow, or communication between objects, apply these patterns: + +- **Strategy:** Use to define a family of algorithms, encapsulate each one, and make them interchangeable. Eliminate complex conditional logic (`switch`/`if-else`) that selects behavior by delegating to a Strategy object. +- **Observer:** Use to define a one-to-many dependency where a change in one object (Subject) automatically notifies and updates others (Observers). Keep subjects and observers loosely coupled. +- **Command:** Use to encapsulate a request as an object. This is essential for implementing undo/redo functionality, queues, or logging requests. +- **State:** Use when an object's behavior depends heavily on its internal state, and it must change its behavior at runtime. Represent each state as a separate class. +- **Template Method:** Use to define the skeleton of an algorithm in a base class, deferring specific steps to subclasses without changing the algorithm's structure. +- **Chain of Responsibility:** Use to pass a request along a chain of potential handlers until one handles it, avoiding coupling the sender to a specific receiver. +- **Mediator:** Use to centralize complex communications and control logic between a set of objects, keeping them from referring to each other explicitly. +- **Iterator:** Use to provide a standard way to sequentially access elements of an aggregate object without exposing its underlying representation. +- **Visitor:** Use to define a new operation on an object structure without changing the classes of the elements on which it operates. This is highly effective for performing different analyses on stable composite structures (like Abstract Syntax Trees). +- **Memento:** Use to capture and externalize an object's internal state without violating encapsulation, allowing the object to be restored later (useful for complex Undo mechanisms). + +## Code Generation Rules for Copilot + +1. **Pattern Recognition:** When prompted to solve a problem that maps to a GoF pattern (e.g., "I need a way to undo this action", "I have multiple ways to calculate taxes"), explicitly mention the pattern you are applying in comments. +2. **Interface First:** Generate the interface or abstract base class *before* generating concrete implementations. +3. **Immutability & Encapsulation:** Make fields `private` by default. Provide getters/setters only when necessary. Favor immutable objects. +4. **Naming Conventions:** Use pattern names in class names where it aids understanding (e.g., `TaxCalculationStrategy`, `ButtonDecorator`, `WidgetFactory`), but keep names natural to the domain when appropriate. +5. **Avoid God Classes:** Break large, complex classes into smaller, focused classes coordinating via a Mediator or composed of smaller Strategy objects. +6. **Single Responsibility Principle:** Ensure each class has only one reason to change. If a class is doing too much, refactor it into multiple classes. +7. **Open/Closed Principle:** Design classes to be open for extension but closed for modification. Use abstract classes or interfaces to allow new behavior without changing existing code. +8. **Liskov Substitution Principle:** Ensure that subclasses can be substituted for their base classes without altering the correctness of the program. Avoid violating this principle by ensuring that derived classes do not strengthen preconditions or weaken postconditions. +9. **Interface Segregation Principle:** Prefer many specific interfaces over a single general-purpose interface. Clients should not be forced to depend on interfaces they do not use. +10. **Dependency Inversion Principle:** Depend on abstractions, not on concretions. High-level modules should not depend on low-level modules; both should depend on abstractions. +11. **Use Design Patterns Judiciously:** Apply patterns when they solve a real problem in the codebase. Avoid over-engineering by applying patterns only when they provide clear benefits in terms of maintainability, flexibility, or readability. +12. **Document Intent:** When using a design pattern, include comments that explain why the pattern was chosen and how it is being applied. This helps future maintainers understand the rationale behind the design decisions. +13. **Testability:** Ensure that the generated code is testable. Use patterns that facilitate unit testing (e.g., Dependency Injection for easier mocking). Write tests that verify the behavior of the patterns in use. +14. **Refactor Iteratively:** When refactoring existing code to apply design patterns, do so iteratively. Start with small, incremental changes that improve the design without introducing bugs. Use tests to verify that behavior remains correct throughout the refactoring process. +15. **Performance Considerations:** Be mindful of the performance implications of design patterns. Some patterns may introduce additional layers of abstraction that can impact performance. Use profiling tools to identify bottlenecks and optimize as necessary without sacrificing maintainability. +16. **Consistency:** Apply design patterns consistently across the codebase. If a particular pattern is used in one part of the code, consider using it in similar situations elsewhere to maintain a consistent design language. +17. **Review and Iterate:** Regularly review the codebase for opportunities to apply design patterns or refactor existing code to better adhere to OOP principles. Encourage code reviews that focus on design quality and adherence to these guidelines. +18. **Stay Updated:** Keep up with the latest developments in OOP design patterns and best practices. Continuously learn and adapt your coding style to incorporate new insights and techniques that can improve the quality of your codebase. +19. **Balance Simplicity and Flexibility:** While design patterns can provide powerful solutions, they can also add complexity. Strive for a balance between simplicity and flexibility, ensuring that the code remains easy to understand and maintain while still being adaptable to future changes. Favor function definition over class definition when the problem can be solved with a simple function, and use classes and patterns when they provide clear organizational benefits. +20. **Use Repositories and Typing definitions:** When generating code that involves complex data structures or interactions, consider using repositories to abstract data access and typing definitions to ensure type safety and clarity in the codebase. This can help maintain a clean separation of concerns and improve the overall maintainability of the code. +21. **Logging and Error Handling:** When applying design patterns, ensure that logging and error handling are integrated appropriately. Use patterns like Decorator to add logging functionality without modifying existing code, and ensure that exceptions are handled gracefully to maintain the robustness of the application. Fail safe, loud, clear and early. Avoid silent failures and ensure that errors are logged with sufficient context to facilitate debugging and maintenance. Use custom exceptions where appropriate to provide more meaningful error messages and to allow for more granular error handling in client code. USe try-catch blocks judiciously, ensuring that they are used to handle expected error conditions rather than to control normal program flow. Use finally blocks to ensure that resources are cleaned up properly, even in the case of exceptions. Use logging frameworks to manage log levels and outputs, allowing for better control over the logging behavior in different environments (e.g., development vs. production). Use info, debug, warning, error and critical log levels appropriately in every class and function to provide clear insights into the application's behavior and potential issues. Consider implementing a centralized error handling mechanism (e.g., a global exception handler) to ensure consistent error responses and logging across the application. +22. **Documentation:** When applying design patterns, ensure that the code is well-documented. Use docstrings written in English to explain the purpose of classes and methods, and include comments that clarify complex logic or design decisions. Use the numpy pattern for documentating the parameters and resturns in the docstring unless another pattern is used in the exisitng code. Ask the developer at the first usage of this instruction which kind of docstring parameter and return he prefers, override the numpy docstring definition here and use this kind of docstring for all later programming tasks. This helps other developers understand the intent behind the code and how to use it effectively. Consider using tools like Sphinx or JSDoc to generate documentation from your codebase, making it easier for developers to navigate and understand the available classes, methods, and their intended usage. Additionally, maintain a high-level architectural overview in a README or dedicated documentation file that explains how different components and patterns fit together within the overall system architecture. Devide your documentation into user documentation (how to use the code) and developer documentation (how the code works and how to maintain it). Ensure that both types of documentation are kept up-to-date as the code evolves. Use diagrams (e.g., UML) where appropriate to visually represent the relationships between classes and patterns, aiding in comprehension for developers who may be new to OOP design patterns. Encourage a culture of documentation within the development team, emphasizing its importance for maintaining a clean and maintainable codebase. Never explode in documentation by creating constantly new documentation files whiuch contain the same. Scan existing doc files to extend them or to build new required doc sheets in the same style as existing ones. Keep it concise, clear and focused on the most important aspects of the code and its design patterns. Avoid redundant or overly verbose documentation that can overwhelm developers and obscure the key information they need to understand the codebase effectively. From 22a85491e8628c0e0c668c84fbe5b7c1cf192dcd Mon Sep 17 00:00:00 2001 From: Marcel Deutzer Date: Sun, 15 Mar 2026 14:10:13 +0100 Subject: [PATCH 2/4] Splitted large texts into smaller instructions. --- .../oop-design-patterns.instructions.md | 67 +++++++++++++------ 1 file changed, 45 insertions(+), 22 deletions(-) diff --git a/instructions/oop-design-patterns.instructions.md b/instructions/oop-design-patterns.instructions.md index 742bb7345..5b388b0ce 100644 --- a/instructions/oop-design-patterns.instructions.md +++ b/instructions/oop-design-patterns.instructions.md @@ -54,25 +54,48 @@ When generating code involving algorithms, control flow, or communication betwee ## Code Generation Rules for Copilot -1. **Pattern Recognition:** When prompted to solve a problem that maps to a GoF pattern (e.g., "I need a way to undo this action", "I have multiple ways to calculate taxes"), explicitly mention the pattern you are applying in comments. -2. **Interface First:** Generate the interface or abstract base class *before* generating concrete implementations. -3. **Immutability & Encapsulation:** Make fields `private` by default. Provide getters/setters only when necessary. Favor immutable objects. -4. **Naming Conventions:** Use pattern names in class names where it aids understanding (e.g., `TaxCalculationStrategy`, `ButtonDecorator`, `WidgetFactory`), but keep names natural to the domain when appropriate. -5. **Avoid God Classes:** Break large, complex classes into smaller, focused classes coordinating via a Mediator or composed of smaller Strategy objects. -6. **Single Responsibility Principle:** Ensure each class has only one reason to change. If a class is doing too much, refactor it into multiple classes. -7. **Open/Closed Principle:** Design classes to be open for extension but closed for modification. Use abstract classes or interfaces to allow new behavior without changing existing code. -8. **Liskov Substitution Principle:** Ensure that subclasses can be substituted for their base classes without altering the correctness of the program. Avoid violating this principle by ensuring that derived classes do not strengthen preconditions or weaken postconditions. -9. **Interface Segregation Principle:** Prefer many specific interfaces over a single general-purpose interface. Clients should not be forced to depend on interfaces they do not use. -10. **Dependency Inversion Principle:** Depend on abstractions, not on concretions. High-level modules should not depend on low-level modules; both should depend on abstractions. -11. **Use Design Patterns Judiciously:** Apply patterns when they solve a real problem in the codebase. Avoid over-engineering by applying patterns only when they provide clear benefits in terms of maintainability, flexibility, or readability. -12. **Document Intent:** When using a design pattern, include comments that explain why the pattern was chosen and how it is being applied. This helps future maintainers understand the rationale behind the design decisions. -13. **Testability:** Ensure that the generated code is testable. Use patterns that facilitate unit testing (e.g., Dependency Injection for easier mocking). Write tests that verify the behavior of the patterns in use. -14. **Refactor Iteratively:** When refactoring existing code to apply design patterns, do so iteratively. Start with small, incremental changes that improve the design without introducing bugs. Use tests to verify that behavior remains correct throughout the refactoring process. -15. **Performance Considerations:** Be mindful of the performance implications of design patterns. Some patterns may introduce additional layers of abstraction that can impact performance. Use profiling tools to identify bottlenecks and optimize as necessary without sacrificing maintainability. -16. **Consistency:** Apply design patterns consistently across the codebase. If a particular pattern is used in one part of the code, consider using it in similar situations elsewhere to maintain a consistent design language. -17. **Review and Iterate:** Regularly review the codebase for opportunities to apply design patterns or refactor existing code to better adhere to OOP principles. Encourage code reviews that focus on design quality and adherence to these guidelines. -18. **Stay Updated:** Keep up with the latest developments in OOP design patterns and best practices. Continuously learn and adapt your coding style to incorporate new insights and techniques that can improve the quality of your codebase. -19. **Balance Simplicity and Flexibility:** While design patterns can provide powerful solutions, they can also add complexity. Strive for a balance between simplicity and flexibility, ensuring that the code remains easy to understand and maintain while still being adaptable to future changes. Favor function definition over class definition when the problem can be solved with a simple function, and use classes and patterns when they provide clear organizational benefits. -20. **Use Repositories and Typing definitions:** When generating code that involves complex data structures or interactions, consider using repositories to abstract data access and typing definitions to ensure type safety and clarity in the codebase. This can help maintain a clean separation of concerns and improve the overall maintainability of the code. -21. **Logging and Error Handling:** When applying design patterns, ensure that logging and error handling are integrated appropriately. Use patterns like Decorator to add logging functionality without modifying existing code, and ensure that exceptions are handled gracefully to maintain the robustness of the application. Fail safe, loud, clear and early. Avoid silent failures and ensure that errors are logged with sufficient context to facilitate debugging and maintenance. Use custom exceptions where appropriate to provide more meaningful error messages and to allow for more granular error handling in client code. USe try-catch blocks judiciously, ensuring that they are used to handle expected error conditions rather than to control normal program flow. Use finally blocks to ensure that resources are cleaned up properly, even in the case of exceptions. Use logging frameworks to manage log levels and outputs, allowing for better control over the logging behavior in different environments (e.g., development vs. production). Use info, debug, warning, error and critical log levels appropriately in every class and function to provide clear insights into the application's behavior and potential issues. Consider implementing a centralized error handling mechanism (e.g., a global exception handler) to ensure consistent error responses and logging across the application. -22. **Documentation:** When applying design patterns, ensure that the code is well-documented. Use docstrings written in English to explain the purpose of classes and methods, and include comments that clarify complex logic or design decisions. Use the numpy pattern for documentating the parameters and resturns in the docstring unless another pattern is used in the exisitng code. Ask the developer at the first usage of this instruction which kind of docstring parameter and return he prefers, override the numpy docstring definition here and use this kind of docstring for all later programming tasks. This helps other developers understand the intent behind the code and how to use it effectively. Consider using tools like Sphinx or JSDoc to generate documentation from your codebase, making it easier for developers to navigate and understand the available classes, methods, and their intended usage. Additionally, maintain a high-level architectural overview in a README or dedicated documentation file that explains how different components and patterns fit together within the overall system architecture. Devide your documentation into user documentation (how to use the code) and developer documentation (how the code works and how to maintain it). Ensure that both types of documentation are kept up-to-date as the code evolves. Use diagrams (e.g., UML) where appropriate to visually represent the relationships between classes and patterns, aiding in comprehension for developers who may be new to OOP design patterns. Encourage a culture of documentation within the development team, emphasizing its importance for maintaining a clean and maintainable codebase. Never explode in documentation by creating constantly new documentation files whiuch contain the same. Scan existing doc files to extend them or to build new required doc sheets in the same style as existing ones. Keep it concise, clear and focused on the most important aspects of the code and its design patterns. Avoid redundant or overly verbose documentation that can overwhelm developers and obscure the key information they need to understand the codebase effectively. +- **Pattern Recognition:** When prompted to solve a problem that maps to a GoF pattern (e.g., "I need a way to undo this action", "I have multiple ways to calculate taxes"), explicitly mention the pattern you are applying in comments. +- **Interface First:** Generate the interface or abstract base class *before* generating concrete implementations. +- **Immutability & Encapsulation:** Make fields `private` by default. Provide getters/setters only when necessary. Favor immutable objects. +- **Naming Conventions:** Use pattern names in class names where it aids understanding (e.g., `TaxCalculationStrategy`, `ButtonDecorator`, `WidgetFactory`), but keep names natural to the domain when appropriate. +- **Avoid God Classes:** Break large, complex classes into smaller, focused classes coordinating via a Mediator or composed of smaller Strategy objects. +- **Single Responsibility Principle:** Ensure each class has only one reason to change. If a class is doing too much, refactor it into multiple classes. +- **Open/Closed Principle:** Design classes to be open for extension but closed for modification. Use abstract classes or interfaces to allow new behavior without changing existing code. +- **Liskov Substitution Principle:** Ensure that subclasses can be substituted for their base classes without altering the correctness of the program. Avoid violating this principle by ensuring that derived classes do not strengthen preconditions or weaken postconditions. +- **Interface Segregation Principle:** Prefer many specific interfaces over a single general-purpose interface. Clients should not be forced to depend on interfaces they do not use. +- **Dependency Inversion Principle:** Depend on abstractions, not on concretions. High-level modules should not depend on low-level modules; both should depend on abstractions. +- **Use Design Patterns Judiciously:** Apply patterns when they solve a real problem in the codebase. Avoid over-engineering by applying patterns only when they provide clear benefits in terms of maintainability, flexibility, or readability. +- **Document Intent:** When using a design pattern, include comments that explain why the pattern was chosen and how it is being applied. This helps future maintainers understand the rationale behind the design decisions. +- **Testability:** Ensure that the generated code is testable. Use patterns that facilitate unit testing (e.g., Dependency Injection for easier mocking). Write tests that verify the behavior of the patterns in use. +- **Refactor Iteratively:** When refactoring existing code to apply design patterns, do so iteratively. Start with small, incremental changes that improve the design without introducing bugs. Use tests to verify that behavior remains correct throughout the refactoring process. +- **Performance Considerations:** Be mindful of the performance implications of design patterns. Some patterns may introduce additional layers of abstraction that can impact performance. Use profiling tools to identify bottlenecks and optimize as necessary without sacrificing maintainability. +- **Consistency:** Apply design patterns consistently across the codebase. If a particular pattern is used in one part of the code, consider using it in similar situations elsewhere to maintain a consistent design language. +- **Review and Iterate:** Regularly review the codebase for opportunities to apply design patterns or refactor existing code to better adhere to OOP principles. Encourage code reviews that focus on design quality and adherence to these guidelines. +- **Stay Updated:** Keep up with the latest developments in OOP design patterns and best practices. Continuously learn and adapt your coding style to incorporate new insights and techniques that can improve the quality of your codebase. +- **Balance Simplicity and Flexibility:** While design patterns can provide powerful solutions, they can also add complexity. Strive for a balance between simplicity and flexibility, ensuring that the code remains easy to understand and maintain while still being adaptable to future changes. Favor function definition over class definition when the problem can be solved with a simple function, and use classes and patterns when they provide clear organizational benefits. +- **Use Repositories and Typing definitions:** When generating code that involves complex data structures or interactions, consider using repositories to abstract data access and typing definitions to ensure type safety and clarity in the codebase. This can help maintain a clean separation of concerns and improve the overall maintainability of the code. + +## Logging and Error Handling + +- When applying design patterns, ensure that logging and error handling are integrated appropriately. +- Use patterns like Decorator to add logging functionality without modifying existing code, and ensure that exceptions are handled gracefully to maintain the robustness of the application. +- Fail safe, loud, clear and early. +- Avoid silent failures and ensure that errors are logged with sufficient context to facilitate debugging and maintenance. +- Use custom exceptions where appropriate to provide more meaningful error messages and to allow for more granular error handling in client code. +- Use try-catch blocks judiciously, ensuring that they are used to handle expected error conditions rather than to control normal program flow. +- Use finally blocks to ensure that resources are cleaned up properly, even in the case of exceptions. +- Use logging frameworks to manage log levels and outputs, allowing for better control over the logging behavior in different environments (e.g., development vs. production). +- Use info, debug, warning, error and critical log levels appropriately in every class and function to provide clear insights into the application's behavior and potential issues. Consider implementing a centralized error handling mechanism (e.g., a global exception handler) to ensure consistent error responses and logging across the application. + +## Documentation + +- When applying design patterns, ensure that the code is well-documented. +- Use docstrings written in English to explain the purpose of classes and methods, and include comments that clarify complex logic or design decisions. Use the numpy pattern for documentating the parameters and resturns in the docstring unless another pattern is used in the exisitng code. Ask the developer at the first usage of this instruction which kind of docstring parameter and return he prefers, override the numpy docstring definition here and use this kind of docstring for all later programming tasks. This helps other developers understand the intent behind the code and how to use it effectively. +- Consider using tools like Sphinx or JSDoc to generate documentation from your codebase, making it easier for developers to navigate and understand the available classes, methods, and their intended usage. +- Additionally, maintain a high-level architectural overview in a README or dedicated documentation file that explains how different components and patterns fit together within the overall system architecture. +- Devide your documentation into user documentation (how to use the code) and developer documentation (how the code works and how to maintain it). Ensure that both types of documentation are kept up-to-date as the code evolves. +- Use diagrams (e.g., UML) where appropriate to visually represent the relationships between classes and patterns, aiding in comprehension for developers who may be new to OOP design patterns. +- Encourage a culture of documentation within the development team, emphasizing its importance for maintaining a clean and maintainable codebase. +- Never explode in documentation by creating constantly new documentation files whiuch contain the same. +- Scan existing doc files to extend them or to build new required doc sheets in the same style as existing ones. Keep it concise, clear and focused on the most important aspects of the code and its design patterns. +- Avoid redundant or overly verbose documentation that can overwhelm developers and obscure the key information they need to understand the codebase effectively. From 38647a815ce75344c53cd1cfce1a7ab1957c9fce Mon Sep 17 00:00:00 2001 From: Marcel Deutzer Date: Sun, 15 Mar 2026 14:16:12 +0100 Subject: [PATCH 3/4] Refactored instruction and misspellings. --- docs/README.instructions.md | 2 +- instructions/oop-design-patterns.instructions.md | 12 +++++------- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/README.instructions.md b/docs/README.instructions.md index c684e7ae1..b9eb2941a 100644 --- a/docs/README.instructions.md +++ b/docs/README.instructions.md @@ -84,7 +84,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-instructions) for guidelines on | [Debian Linux Administration Guidelines](../instructions/debian-linux.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdebian-linux.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdebian-linux.instructions.md) | Guidance for Debian-based Linux administration, apt workflows, and Debian policy conventions. | | [Define Events (Preview)](../instructions/pcf-events.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpcf-events.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpcf-events.instructions.md) | Define and handle custom events in PCF components | | [Dependent Libraries (Preview)](../instructions/pcf-dependent-libraries.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpcf-dependent-libraries.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpcf-dependent-libraries.instructions.md) | Using dependent libraries in PCF components | -| [Design Patterns for Object-Oriented Programming for Clean Code](../instructions/oop-design-patterns.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Foop-design-patterns.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Foop-design-patterns.instructions.md) | Best practices for applying Object-Oriented Programming (OOP) design patterns, including Gang of Four (GoF) patterns and SOLID principles | +| [Design Patterns for Object-Oriented Programming for Clean Code](../instructions/oop-design-patterns.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Foop-design-patterns.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Foop-design-patterns.instructions.md) | Best practices for applying Object-Oriented Programming (OOP) design patterns, including Gang of Four (GoF) patterns and SOLID principles, to ensure clean, maintainable, and scalable code. | | [Dev Box image definitions](../instructions/devbox-image-definition.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdevbox-image-definition.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdevbox-image-definition.instructions.md) | Authoring recommendations for creating YAML based image definition files for use with Microsoft Dev Box Team Customizations | | [DevOps Core Principles](../instructions/devops-core-principles.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdevops-core-principles.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdevops-core-principles.instructions.md) | Foundational instructions covering core DevOps principles, culture (CALMS), and key metrics (DORA) to guide GitHub Copilot in understanding and promoting effective software delivery. | | [Dotnet Wpf](../instructions/dotnet-wpf.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-wpf.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-wpf.instructions.md) | .NET WPF component and application patterns | diff --git a/instructions/oop-design-patterns.instructions.md b/instructions/oop-design-patterns.instructions.md index 5b388b0ce..d62f969b7 100644 --- a/instructions/oop-design-patterns.instructions.md +++ b/instructions/oop-design-patterns.instructions.md @@ -1,6 +1,6 @@ --- description: 'Best practices for applying Object-Oriented Programming (OOP) design patterns, including Gang of Four (GoF) patterns and SOLID principles, to ensure clean, maintainable, and scalable code.' -applyTo: '*' +applyTo: '**/*.py, **/*.java, **/*.ts, **/*.js, **/*.cs' --- @@ -78,24 +78,22 @@ When generating code involving algorithms, control flow, or communication betwee ## Logging and Error Handling - When applying design patterns, ensure that logging and error handling are integrated appropriately. -- Use patterns like Decorator to add logging functionality without modifying existing code, and ensure that exceptions are handled gracefully to maintain the robustness of the application. - Fail safe, loud, clear and early. - Avoid silent failures and ensure that errors are logged with sufficient context to facilitate debugging and maintenance. - Use custom exceptions where appropriate to provide more meaningful error messages and to allow for more granular error handling in client code. -- Use try-catch blocks judiciously, ensuring that they are used to handle expected error conditions rather than to control normal program flow. -- Use finally blocks to ensure that resources are cleaned up properly, even in the case of exceptions. +- Use exception blocks judiciously, ensuring that they are used to handle expected error conditions rather than to control normal program flow. - Use logging frameworks to manage log levels and outputs, allowing for better control over the logging behavior in different environments (e.g., development vs. production). - Use info, debug, warning, error and critical log levels appropriately in every class and function to provide clear insights into the application's behavior and potential issues. Consider implementing a centralized error handling mechanism (e.g., a global exception handler) to ensure consistent error responses and logging across the application. ## Documentation - When applying design patterns, ensure that the code is well-documented. -- Use docstrings written in English to explain the purpose of classes and methods, and include comments that clarify complex logic or design decisions. Use the numpy pattern for documentating the parameters and resturns in the docstring unless another pattern is used in the exisitng code. Ask the developer at the first usage of this instruction which kind of docstring parameter and return he prefers, override the numpy docstring definition here and use this kind of docstring for all later programming tasks. This helps other developers understand the intent behind the code and how to use it effectively. +- Use docstrings written in English to explain the purpose of classes and methods, and include comments that clarify complex logic or design decisions. Use the numpy pattern for documentating the parameters and resturns in the docstring unless another pattern is used in the existing code. Ask the developer at the first usage of this instruction which kind of docstring parameter and return he prefers, override the numpy docstring definition here and use this kind of docstring for all later programming tasks. This helps other developers understand the intent behind the code and how to use it effectively. - Consider using tools like Sphinx or JSDoc to generate documentation from your codebase, making it easier for developers to navigate and understand the available classes, methods, and their intended usage. - Additionally, maintain a high-level architectural overview in a README or dedicated documentation file that explains how different components and patterns fit together within the overall system architecture. -- Devide your documentation into user documentation (how to use the code) and developer documentation (how the code works and how to maintain it). Ensure that both types of documentation are kept up-to-date as the code evolves. +- Divide your documentation into user documentation (how to use the code) and developer documentation (how the code works and how to maintain it). Ensure that both types of documentation are kept up-to-date as the code evolves. - Use diagrams (e.g., UML) where appropriate to visually represent the relationships between classes and patterns, aiding in comprehension for developers who may be new to OOP design patterns. - Encourage a culture of documentation within the development team, emphasizing its importance for maintaining a clean and maintainable codebase. -- Never explode in documentation by creating constantly new documentation files whiuch contain the same. +- Never explode in documentation by creating constantly new documentation files which contain the same content. - Scan existing doc files to extend them or to build new required doc sheets in the same style as existing ones. Keep it concise, clear and focused on the most important aspects of the code and its design patterns. - Avoid redundant or overly verbose documentation that can overwhelm developers and obscure the key information they need to understand the codebase effectively. From 8ac30a687617a015ee5e97b3d60b8cc61e5ac4a4 Mon Sep 17 00:00:00 2001 From: Marcel Deutzer Date: Sun, 15 Mar 2026 14:21:13 +0100 Subject: [PATCH 4/4] Correct misspellings. --- instructions/oop-design-patterns.instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/instructions/oop-design-patterns.instructions.md b/instructions/oop-design-patterns.instructions.md index d62f969b7..c8c4242cf 100644 --- a/instructions/oop-design-patterns.instructions.md +++ b/instructions/oop-design-patterns.instructions.md @@ -88,7 +88,7 @@ When generating code involving algorithms, control flow, or communication betwee ## Documentation - When applying design patterns, ensure that the code is well-documented. -- Use docstrings written in English to explain the purpose of classes and methods, and include comments that clarify complex logic or design decisions. Use the numpy pattern for documentating the parameters and resturns in the docstring unless another pattern is used in the existing code. Ask the developer at the first usage of this instruction which kind of docstring parameter and return he prefers, override the numpy docstring definition here and use this kind of docstring for all later programming tasks. This helps other developers understand the intent behind the code and how to use it effectively. +- Use docstrings written in English to explain the purpose of classes and methods, and include comments that clarify complex logic or design decisions. Use the numpy pattern for documenting the parameters and returns in the docstring unless another pattern is used in the existing code. Ask the developer at the first usage of this instruction which kind of docstring parameter and return he prefers, override the numpy docstring definition here and use this kind of docstring for all later programming tasks. This helps other developers understand the intent behind the code and how to use it effectively. - Consider using tools like Sphinx or JSDoc to generate documentation from your codebase, making it easier for developers to navigate and understand the available classes, methods, and their intended usage. - Additionally, maintain a high-level architectural overview in a README or dedicated documentation file that explains how different components and patterns fit together within the overall system architecture. - Divide your documentation into user documentation (how to use the code) and developer documentation (how the code works and how to maintain it). Ensure that both types of documentation are kept up-to-date as the code evolves.