General Code Guidelines

code-guideline.md

To be used with github copilot create a file as '.github/copilot-instructions.md' & add below

Before making any code modifications/suggestions, if you identify any unresolved queries or logical inconsistencies whether in the overall project design or the specific code change please ask for clarification before proceeding

Follow all below coding principles and guidelines while making any code changes:

1. DRY (Don't Repeat Yourself): Eliminate code duplication to enhance maintainability.
2. KISS (Keep It Simple, Stupid): Favor simplicity; avoid unnecessary complexity.
3. YAGNI (You Aren't Gonna Need It): Implement features only when necessary.
4. SOLID Principles:
   1. Single Responsibility: Each module/class should have one responsibility.
   2. Open/Closed: Modules should be open for extension but closed for modification.
   3. Liskov Substitution: Subclasses should be substitutable for their base classes.
   4. Interface Segregation: Prefer many specific interfaces over a single general-purpose one.
   5. Dependency Inversion: Depend on abstractions, not concrete implementations.
5. Separation of Concerns: Divide code into distinct sections, each addressing a specific concern.
6. Avoid Premature Optimization: Optimize only after identifying performance bottlenecks.
7. Law of Demeter: A module should only communicate with its immediate collaborators.
8. Composition Over Inheritance: Favor composition to achieve flexibility and reusability.
9. Encapsulate What Varies: Isolate the parts of the code that are subject to change.
10. Program to an Interface: Depend on abstractions rather than concrete implementations.
11. Minimize Coupling: Reduce dependencies between modules to enhance modularity.
12. Maximize Cohesion: Ensure that elements within a module are closely related in functionality.
13. Boy Scout Rule: Leave the code cleaner than you found it.
14. Principle of Least Astonishment: Code should behave in a way that least surprises other developers.
15. Fail Fast: Design systems to fail immediately upon encountering an error.

Code Size Guidelines for Python

To maintain readability and ease of maintenance, follow these size guidelines:

File Size

• Optimal: 100-300 lines per file
• Maximum: 500 lines
• Action Required: If a file exceeds 500 lines, consider splitting it into multiple files with focused responsibilities

Class Size

• Optimal: 50-200 lines per class
• Maximum: 300 lines
• Action Required: If a class exceeds 300 lines, consider:
  • Breaking it into smaller classes
  • Using composition to distribute functionality
  • Creating mixins or utility classes for shared behaviors

Method/Function Size

• Optimal: 5-15 lines per method/function
• Maximum: 40 lines
• Action Required: If a function exceeds 40 lines, consider:
  • Breaking it into smaller functions with clear names
  • Extracting repeated patterns into helper functions
  • Using higher-order functions for recurring patterns

Other Guidelines

• Line Length: Maximum 88 characters per line (follows Black formatter convention)
• Nesting: Maximum 3 levels of nesting for control structures
• Parameters: Maximum 5 parameters per function; use dataclasses or dictionaries for more
• Import Statements: Group imports (standard library, third-party, local) and limit to 15 per file

Remember: These are guidelines, not strict rules. Use judgment when exceptional cases arise, but document why you're exceeding the guidelines when necessary.