Skip to content

Instantly share code, notes, and snippets.

@samkeen
Last active September 16, 2025 18:51
Show Gist options
  • Save samkeen/f473e261d35bb9df6d6ebfb97274b06f to your computer and use it in GitHub Desktop.
Save samkeen/f473e261d35bb9df6d6ebfb97274b06f to your computer and use it in GitHub Desktop.
This is an evolving general purpose (js & Python) software dev constitution

Of course. Here is the updated constitution with those three principles integrated.


Core Philosophy & Architecture 🏛️

  • Follow SOLID Principles: Adhere strictly to the five SOLID principles (Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion) to create a modular, scalable, and maintainable architecture.
  • Explicit is Better than Implicit: Code should be clear and self-evident. Avoid clever tricks or "magic" that hide the underlying logic. The flow of data and control should be easy to follow.
  • Simplicity and YAGNI: Prioritize simplicity and adhere to the "You Ain't Gonna Need It" principle. Do not add functionality or complexity until it is actively required.
  • Manage State Predictably: Application state must be handled in a centralized and predictable manner. Avoid scattering state logic throughout the codebase. State changes should be explicit and traceable, minimizing side effects and making the application easier to debug.
  • Use DI to Minimize Mocking: In testing, avoid mocking unless absolutely necessary. View the need for excessive mocking as a sign of tight coupling. In such cases, review the architecture and propose corrections, such as using Dependency Injection (DI), to decouple components.

Code Quality & Readability ✍️

  • Follow the DRY Principle: Don't Repeat Yourself. Abstract any duplicated logic into reusable functions, classes, or modules to improve maintainability and reduce redundancy.
  • Adhere to Naming Conventions: Use clear, descriptive names and follow language-specific best practices:
    • JavaScript: Use camelCase for variables and functions, and PascalCase for classes.
    • Python: Use snake_case for variables and functions, and PascalCase for classes (per PEP 8).
  • Functions Must Have a Single Responsibility: Each function should do one thing and do it well. A function that retrieves data should not also be responsible for formatting or displaying it.
  • Minimize Code Comments: Comments should be used sparingly. Code should be self-documenting. Only add comments to explain the "why" behind complex or non-obvious logic, never the "what."

Project Structure & Documentation 📂

  • Adopt Standard Project Structures: Follow the recommended project structure for the primary framework being used (e.g., the standard layout for a Django, Flask, or React project). If no framework is used, organize the project logically by separating concerns (e.g., data/, services/, presentation/).
  • Maintain a Comprehensive README.md: Every project must have a README.md file at its root. This file should be kept up-to-date with a project description, setup and installation instructions, and a brief architectural overview.
  • .gitignore Every project MUST have a .gitignore file following common practices for the language and operating system.

Process & Security ⚙️

  • Test-First Development (TDD) is Non-Negotiable: All development must follow the "Red-Green-Refactor" cycle. A failing test that reproduces the bug or defines the new feature must be written before any implementation begins.
  • Prioritize Observability: Do not use print statements. All components must emit structured logs, metrics, and traces to provide a complete picture of the system's health and behavior. Logging must use a centralized configuration with adjustable levels (e.g., DEBUG, INFO, ERROR).
  • Implement Robust Error Handling: The application must handle potential errors gracefully. Do not let exceptions go unhandled. Implement try-catch/except blocks and provide clear, actionable error messages where appropriate.
  • Sanitize All External Input: Treat all input from external sources (user input, API responses, file reads) as untrusted. Sanitize and validate this data to prevent security vulnerabilities like Cross-Site Scripting (XSS) and injection attacks.
  • Make Atomic Commits: Each commit to version control should represent a single, logical change. Write clear and concise commit messages that describe the change. This creates a clean, understandable project history.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment